Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 13 additions & 2 deletions .cursor-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,12 +1,23 @@
{
"name": "serpapi",
"description": "Search Google, Amazon, Walmart, YouTube, and 50+ engines via SerpApi",
"version": "1.0.0",
"version": "1.1.0",
"author": {
"name": "SerpApi"
},
"homepage": "https://serpapi.com",
"repository": "https://github.com/serpapi/serpapi-cursor-plugin",
"license": "MIT",
"keywords": ["search", "google", "amazon", "walmart", "serp", "seo", "scraping"]
"keywords": ["search", "google", "amazon", "walmart", "serp", "seo", "scraping"],
"variables": {
"type": "object",
"properties": {
"SERPAPI_API_KEY": {
"type": "string",
"title": "SerpApi API key",
"description": "API key from https://serpapi.com/manage-api-key."
}
},
"required": ["SERPAPI_API_KEY"]
}
}
28 changes: 19 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# <img src="https://user-images.githubusercontent.com/307597/154772945-1b7dba5f-21cf-41d0-bb2e-65b6eff4aaaf.png" width="30" height="30"/> SerpApi Plugin for Cursor

A [Cursor plugin](https://cursor.com/docs/plugins) that gives Cursor Agent the ability to search Google, Amazon, Walmart, YouTube, Google Maps, Google Scholar, and [100+ other engines](https://serpapi.com/search-engine-apis) via the [SerpApi](https://serpapi.com) REST API.
A [Cursor plugin](https://cursor.com/docs/plugins) that gives Cursor Agent the ability to search Google, Amazon, Walmart, YouTube, Google Maps, Google Scholar, and [100+ other engines](https://serpapi.com/search-engine-apis) through [SerpApi](https://serpapi.com).

[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Engines](https://img.shields.io/badge/engines-112-blue.svg)](engines/)
Expand All @@ -11,14 +11,10 @@ A [Cursor plugin](https://cursor.com/docs/plugins) that gives Cursor Agent the a

### 1. Get an API key

Sign up at [serpapi.com](https://serpapi.com/users/sign_up?plan=free) and set the key:
Sign up at [serpapi.com](https://serpapi.com/users/sign_up?plan=free) and copy your key from [serpapi.com/manage-api-key](https://serpapi.com/manage-api-key).

> **Free tier** - 250 searches/month, no credit card required.

```bash
export SERPAPI_API_KEY="your_key_here"
```

### 2. Install the plugin

**Local install** (recommended for testing):
Expand All @@ -37,7 +33,19 @@ Then restart Cursor or run `Developer: Reload Window` from the command palette.

Search for "serpapi" in the Cursor marketplace panel, or visit [cursor.com/marketplace](https://cursor.com/marketplace).

### 3. Use it
### 3. Add your API key

Open the SerpApi plugin in Cursor's **Customize** page, choose **Configure**, and enter your key as **SerpApi API key**. The bundled SerpApi MCP server sends it with each search. On a team-managed install, an admin sets it in the dashboard under **Plugins → Configure**.

To use `curl` instead, or if a search reports a missing key, run setup in chat. Cursor guides you through saving the key in your system keychain or a private file, then runs a test search:

```
/serpapi-setup
```

A `SERPAPI_API_KEY` already exported in your shell keeps working with `curl`.

### 4. Use it

Cursor Agent will automatically use SerpApi when you ask it to search for something. Just ask in natural language:

Expand All @@ -61,7 +69,9 @@ You can also attach it as context:

## Features

- **Single skill, all engines** - `/search` covers all 100+ SerpApi engines. Cursor Agent picks the right one based on your intent.
- **One search skill, all engines** - `/search` covers all 100+ SerpApi engines. Cursor Agent picks the right one based on your intent.
- **MCP included** - Bundles SerpApi's hosted MCP server, so searches need no shell. Falls back to `curl` when the server isn't available.
- **Guided setup** - `/serpapi-setup` stores your key without it appearing in chat, then verifies a real search.
- **Always up to date** - Engine parameter schemas are auto-generated and kept fresh by weekly CI.
- **Auto-invocation** - Cursor Agent detects search-related requests and loads the skill automatically. No need to remember slash commands.
- **Cost-aware** - Defaults to `google_light` (faster, cheaper) for simple web searches. Confirms before making API calls.
Expand All @@ -87,7 +97,7 @@ See the full list in [`engines/`](engines/).

## Troubleshooting

- **"Invalid API key"**: Verify at [serpapi.com/manage-api-key](https://serpapi.com/manage-api-key)
- **"Invalid API key" or "Missing API key"**: Check the key in the plugin's settings and at [serpapi.com/manage-api-key](https://serpapi.com/manage-api-key), or run `/serpapi-setup`
- **Plugin not showing up**: Ensure files are in `~/.cursor/plugins/local/serpapi/` and restart Cursor
- **Skill not loading**: Run `Developer: Reload Window` from the command palette
- **Rate limit exceeded**: Wait or [upgrade your plan](https://serpapi.com/pricing)
Expand Down
11 changes: 11 additions & 0 deletions mcp.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
{
"mcpServers": {
"serpapi": {
"type": "http",
"url": "https://mcp.serpapi.com/mcp",
"headers": {
"Authorization": "Bearer ${SERPAPI_API_KEY}"
}
}
}
}
59 changes: 40 additions & 19 deletions skills/search/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,33 +1,45 @@
---
name: search
description: Search Google, Bing, Amazon, Walmart, YouTube, Google Maps, Google Scholar, and 100+ other engines via the SerpApi REST API. Calls the API using curl. Use when the user wants to search the web, find products or prices, look up local businesses, research academic papers, check news, find jobs, compare flights or hotels, analyze SERPs, or retrieve any search engine results.
description: Search Google, Bing, Amazon, Walmart, YouTube, Google Maps, Google Scholar, and 100+ other engines through SerpApi, using the plugin's SerpApi MCP server or curl. Use when the user wants to search the web, find products or prices, look up local businesses, research academic papers, check news, find jobs, compare flights or hotels, analyze SERPs, or retrieve any search engine results. If access or a key is missing, follow serpapi-setup.
---

# SerpApi Search

Search any engine via a single REST endpoint. Each API call costs one search credit.
Search any engine through SerpApi with the same parameters on either route below. Each API call costs one search credit.

**Important:** Always use `curl` via the Shell tool to call the SerpApi REST API. Do not use WebFetch, WebSearch, or any other HTTP tool.
## Access

## Setup
Use the first route that works and keep it for the rest of the task. The user's explicit choice of route overrides this order.

The API key must be set as an environment variable:
1. **SerpApi MCP server (default).** If the plugin's `serpapi` MCP server exposes a `search` tool, call it. Its key comes from Cursor's plugin settings, so nothing is needed in the shell.
2. **curl (fallback).** If the MCP tools are unavailable, or `search` returns `Missing API key` or `Invalid SerpApi API key`, use `curl` via the Shell tool with `SERPAPI_API_KEY`. If the variable is not set in the shell, load it from a stored source in the same command as the request, as described in [credentials](../serpapi-setup/references/credentials.md). In PowerShell, call `curl.exe` and read `$env:SERPAPI_API_KEY`; the [cURL guide](../serpapi-setup/references/curl.md) has a recipe for each shell.
3. **Neither works.** Follow the [serpapi-setup](../serpapi-setup/SKILL.md) skill, discovering it by name if the link is unavailable. Keep the request pending, never ask for the key in chat, and ask before substituting another provider.

```bash
export SERPAPI_API_KEY="your_key_here"
```
Do not use WebFetch, WebSearch, or any other HTTP tool for SerpApi requests.

## Request Pattern

If `SERPAPI_API_KEY` is not set, tell the user:
> Set your SerpApi API key: `export SERPAPI_API_KEY="your_key"` — get one free at https://serpapi.com/manage-api-key
Every search follows the same pattern regardless of engine.

## API Pattern
MCP `search` tool, with the parameters inside `params`:

```json
{"params": {"engine": "ENGINE", "QUERY_PARAM": "QUERY"}, "mode": "compact"}
```

Every search follows the same pattern regardless of engine:
`mode: "compact"` removes response metadata; omit it for the full response. Do not put `api_key` in `params`.

curl:

```bash
curl -s "https://serpapi.com/search.json?engine=ENGINE&QUERY_PARAM=QUERY&api_key=$SERPAPI_API_KEY"
printf '%s' "$SERPAPI_API_KEY" | curl -q -s --get 'https://serpapi.com/search.json' \
--data-urlencode 'api_key@-' \
--data-urlencode 'engine=ENGINE' \
--data-urlencode 'QUERY_PARAM=QUERY'
```

The key is piped in, so it never appears in curl's arguments, and curl URL-encodes each value. Keep `-q` first: it makes curl ignore `~/.curlrc`, where a verbose or trace setting would print the key.

The only things that vary per engine are:
1. The `engine` value
2. The query parameter name (`q`, `k`, `query`, etc.)
Expand Down Expand Up @@ -84,6 +96,8 @@ Pick the engine based on user intent:

Each engine has its own parameters documented in a JSON schema file at `engines/<engine_name>.json` relative to this plugin's root directory. Read the relevant file when you need engine-specific parameter details.

These bundled files are the default source. Only when an engine has no bundled file, read the MCP resource `serpapi://engines/<engine_name>` from the `serpapi` server; `serpapi://engines` lists every engine.

The JSON schema structure:
- `params`: engine-specific parameters (query, filters, pagination, etc.)
- `common_params`: shared SerpApi parameters (api_key, device, no_cache, etc.)
Expand Down Expand Up @@ -128,25 +142,32 @@ For price comparisons or cross-engine research, query multiple engines sequentia

```bash
# Compare prices across Amazon, Walmart, and Google Shopping
curl -s "https://serpapi.com/search.json?engine=amazon&k=airpods+pro&api_key=$SERPAPI_API_KEY"
curl -s "https://serpapi.com/search.json?engine=walmart&query=airpods+pro&api_key=$SERPAPI_API_KEY"
curl -s "https://serpapi.com/search.json?engine=google_shopping&q=airpods+pro&api_key=$SERPAPI_API_KEY"
printf '%s' "$SERPAPI_API_KEY" | curl -q -s --get 'https://serpapi.com/search.json' \
--data-urlencode 'api_key@-' --data-urlencode 'engine=amazon' --data-urlencode 'k=airpods pro'
printf '%s' "$SERPAPI_API_KEY" | curl -q -s --get 'https://serpapi.com/search.json' \
--data-urlencode 'api_key@-' --data-urlencode 'engine=walmart' --data-urlencode 'query=airpods pro'
printf '%s' "$SERPAPI_API_KEY" | curl -q -s --get 'https://serpapi.com/search.json' \
--data-urlencode 'api_key@-' --data-urlencode 'engine=google_shopping' --data-urlencode 'q=airpods pro'
```

Consolidate and compare the results for the user.

On the MCP route, make one `search` call per engine with the same parameters.

## Rules

1. **Always use `curl` via the Shell tool.** Do not use WebFetch, WebSearch, or other HTTP tools.
1. **Use the SerpApi MCP tools or `curl` via the Shell tool**, in the order under Access. Do not use WebFetch, WebSearch, or other HTTP tools.
2. **Confirm before searching** when the query or engine choice is ambiguous. Each non-cached call costs one credit.
3. **Show the curl command** before executing so the user sees exactly what's being called.
3. **Show the request** before executing, as tool arguments or the curl command, so the user sees exactly what's being called.
4. **Prefer `google_light`** over `google` for simple web searches.
5. **Use `no_cache=false`** (the default) to benefit from free cached results.
6. **URL-encode query parameters** properly. Spaces become `+` or `%20`.
6. **Let curl encode parameters.** Pass each one as `--data-urlencode 'name=value'` with the value in plain text. MCP `params` values are plain text too.
7. **Read the engine schema** from `engines/<engine>.json` when you need to look up available parameters for a specific engine.
8. **On a key or access failure**, stop repeating the call and follow `serpapi-setup`. Never ask for the key in chat.

## Additional Resources

- Setup and repair: [serpapi-setup](../serpapi-setup/SKILL.md)
- For practical curl examples, see [examples.md](examples.md)
- Interactive playground: https://serpapi.com/playground
- Full API docs: https://serpapi.com/search-api
Expand Down
Loading
Loading