Skip to content

README.md

Latest commit

 

History

History
146 lines (108 loc) · 6.68 KB

README.md

File metadata and controls

146 lines (108 loc) · 6.68 KB
Raw

opencode-serpapi

An OpenCode plugin for SerpApi search across Google, Amazon, Walmart, eBay, YouTube, Google Maps, Google Scholar, and 100+ other engines. OpenCode 2 also registers SerpApi's hosted MCP server and native web-search provider.

MIT License

Quick Start

1. Get an API key

Sign up at serpapi.com and set the key:

Free tier – 250 searches/month, no credit card required.

export SERPAPI_API_KEY="your_serpapi_key"

2. Install the plugin

Use the configuration key for your OpenCode version. OpenCode automatically installs npm plugins at startup.

OpenCode 2

Add the package to plugins in opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": ["opencode-serpapi"]
}

OpenCode 1.18.29 and later

Add the package to plugin in opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-serpapi"]
}

Restart OpenCode (or start a new session). The package supports both plugin interfaces from one entrypoint: V1 uses server(), while V2 uses setup().

3. Use it

Ask in natural language and the agent picks the tool and engine on its own:

Search Google for the best Python web frameworks

Compare prices for AirPods Pro on Amazon, Walmart, and eBay

Find academic papers about transformer architectures published after 2020

Find well-reviewed coffee shops near Times Square

How it works

The plugin's integrations depend on the OpenCode version:

  • OpenCode 2 registers the hosted SerpApi MCP server at https://mcp.serpapi.com/mcp, using SERPAPI_API_KEY as its bearer header when available. It also registers SerpApi as a native web-search provider without changing OpenCode's provider selection, plus a direct HTTPS tool named serpapi_rest_search. Existing user-defined MCP configuration is preserved.
  • OpenCode 1 registers the direct HTTPS tool as serpapi_search and adds the bundled skill path. It does not automatically register the hosted MCP server or a native web-search provider.

Both direct tools call https://serpapi.com/search.json with the runtime's built-in fetch and read SERPAPI_API_KEY from the OpenCode process. The bundled serpapi-web-search skill provides engine selection, credential safety, and response guidance.

Features

  • MCP-native search (OpenCode 2) — OpenCode receives the search tool from the serpapi MCP server.
  • OpenCode 2 web search provider — SerpApi results are available through OpenCode's native web-search API.
  • All SerpApi engines — the MCP server supports Google, Bing, Amazon, Walmart, eBay, YouTube, Google Maps, Google Scholar, and other engines.
  • MCP header authentication (OpenCode 2) — the key is read from SERPAPI_API_KEY and sent in the MCP Authorization header, not embedded in the MCP URL or source code.
  • Structured results — the MCP server supports JSON, compact responses, Markdown output, and engine-specific parameter validation.
  • Local search guidance — the bundled skill helps the model choose engines and use engine-specific parameters without owning credentials or making API requests.
  • Direct HTTPS search — serpapi_search on OpenCode 1 and serpapi_rest_search on OpenCode 2 use built-in fetch, with no CLI, shell, or cURL dependency.
  • Engine-aware queries — the native tool maps its generic q argument to engine-specific fields such as Amazon's k, Walmart's query, eBay's _nkw, and YouTube's search_query.

Supported Engines

Category Engines
Web Search Google, Google Light, Bing, DuckDuckGo, Yahoo, Yandex, Baidu, Naver
AI Search Google AI Mode, Google AI Overview, Bing Copilot, Brave AI Mode
Shopping Amazon, Walmart, eBay, Google Shopping, Home Depot
Local / Maps Google Maps, Google Local, Yelp, TripAdvisor, OpenTable
Research Google Scholar, Google Patents, Google Trends
News Google News
Media Google Images, Google Videos, YouTube, Google Lens
Travel Google Flights, Google Hotels, Google Travel Explore
Jobs Google Jobs
Finance Google Finance
Apps Google Play, Apple App Store

Engines not listed in the plugin's query-field map still pass through with q. See the full, current list at serpapi.com/search-engine-apis. Detailed engine, MCP, CLI, REST, credential, and response guidance is bundled under skills/serpapi-web-search/references/.

Troubleshooting

  • "Tool not showing up" — confirm opencode-serpapi is listed under plugins on OpenCode 2 or plugin on OpenCode 1, confirm SERPAPI_API_KEY is available to OpenCode, and restart OpenCode.
  • "Invalid API key" — replace SERPAPI_API_KEY with the current key from the SerpApi dashboard. On OpenCode 2, restart OpenCode so the MCP header is rebuilt.
  • MCP connection problems (OpenCode 2) — run opencode mcp list; the serpapi entry should report connected. OpenCode 1 does not auto-register this MCP server.
  • Search request failure — direct tools return SerpApi search failed: ...; the V2 provider reports SerpApi web search failed: .... Both redact the configured key.

For direct HTTPS fallback, use serpapi_rest_search on OpenCode 2 or serpapi_search on OpenCode 1. On OpenCode 2, the MCP search tool and direct REST fallback have distinct names. Confirm that SERPAPI_API_KEY is available to the OpenCode process.

Development

npm install
npm test
npm run typecheck

The test suite mocks fetch and covers request parameter mapping, trusted-key enforcement, HTTP failures, missing credentials, redaction of web-search provider errors, and V2 MCP/provider registration. OpenCode 1 exposes serpapi_search; OpenCode 2 exposes the MCP search tool and the separately named serpapi_rest_search fallback. The bundled skill provides routing and operational guidance; engines.ts supplies query-field mapping for direct requests.

Related

License

MIT License — see LICENSE file for details.