<img src="logo.png" alt="" width="88" align="right">

# serpens-mcp

MCP server for **SERPens — Google Search & SERP API**. Gives an AI agent live Google
results: organic links, snippets, sitelinks, People Also Ask, related searches, and
Google's AI Overview.

**Zero dependencies.** One file of protocol, one HTTP client, nothing else — `npx` starts
it in under a second and there is no third-party code between your agent and the API.

## Install

Get a key from [the API listing](https://rapidapi.com/starnikovoleg/api/serpens),
then add the server to your client.

**Claude Desktop** — `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "serpens": {
      "command": "npx",
      "args": ["-y", "serpens-mcp"],
      "env": { "SERPENS_API_KEY": "your-rapidapi-key" }
    }
  }
}
```

**Claude Code:**

```bash
claude mcp add serpens --env SERPENS_API_KEY=your-rapidapi-key -- npx -y serpens-mcp
```

**Cursor, Windsurf, Zed and other stdio clients** take the same `command` / `args` / `env`
shape as the JSON above.

## Tools

| Tool | What it returns |
|---|---|
| `google_search` | Organic results — title, link, snippet, source, position — plus sitelinks, People Also Ask and related searches when Google renders them |
| `google_ai_overview` | Google's AI Overview with citations, alongside organic results. When Google renders no overview, organic results still come back |

Both accept the same arguments:

| Argument | Type | Notes |
|---|---|---|
| `q` | string, required | Google operators work: `site:github.com fastify` |
| `gl` | string | Country, two lowercase letters. Default `us` |
| `hl` | string | Interface language, `en` or `en-gb`. Default `en` |
| `page` | integer ≥ 1 | **No upper bound.** Page 40 is a call like any other |
| `tbs` | string | Google time/filter token, e.g. `qdr:d` for the past day |
| `autocorrect` | boolean | Default `true` |
| `format` | `markdown` \| `json` | Default `markdown` |

## Output

By default results come back as Markdown, because that is what a model reads best:

```markdown
# Search results: fastify nodejs

## Organic results

### 1. [Fastify](https://fastify.dev/)
fastify.dev
Fast and low overhead web framework, for Node.js
  - [Documentation](https://fastify.dev/docs/)
```

Pass `format: "json"` to get the raw API response instead, unchanged, when your pipeline
wants to parse fields itself.

## Configuration

| Variable | Default | Purpose |
|---|---|---|
| `SERPENS_API_KEY` | — | Required. `RAPIDAPI_KEY` also works |
| `SERPENS_HOST` | `serpens.p.rapidapi.com` | Override the API host |
| `SERPENS_TIMEOUT_MS` | `30000` | Client-side request timeout |

## Why a package and not a remote MCP URL

The API also speaks MCP over HTTP, so you can point a client straight at it. Going through
this package costs you less: the marketplace bills every request on a declared path,
`initialize` and `tools/list` included, and an agent sends those on every connect. Here the
handshake is local and only searches reach the network.

## Coming from Serper

The underlying API returns Serper's response shape field for field on the `/search`
endpoint, so an existing Serper integration migrates by changing the base URL. This package
is for the agent path; the REST path needs no wrapper at all.

Image, news, places, scholar and shopping verticals are not implemented — if your
integration calls those, it needs more than a base-URL change.

## Errors

Tool errors carry the API's own `error.code` so you can branch on it:

```
invalid_gl: gl must be two lowercase letters
capacity_unavailable: no capacity right now (transient — retrying may help)
```

## License

MIT