# go_serper_mcp_server

A Go implementation of an MCP server that exposes the full Serper Google Search API surface, plus Serper's webpage scrape endpoint.

## Requirements

- Go 1.23+
- A Serper API key (`SERPER_API_KEY`)

## Available Tools

- `google_search`
- `google_search_images`
- `google_search_videos`
- `google_search_places`
- `google_search_maps`
- `google_search_reviews`
- `google_search_news`
- `google_search_shopping`
- `google_search_lens`
- `google_search_scholar`
- `google_search_patents`
- `google_search_autocomplete`
- `webpage_scrape`

## Configuration

Set your Serper API key as an environment variable:

```bash
export SERPER_API_KEY="your-key"
```

Optional:

- `AIOHTTP_TIMEOUT` (seconds, default: 15) - matches the reference server's timeout env name.

## Running

### Stdio (default for most MCP clients)

```bash
go run . -t stdio
```

### SSE

```bash
go run . -t sse -p 8894
```

SSE endpoint:

```
http://localhost:8894/sse
```

## Build

```bash
make build
```

Binary output: `./go_serper_mcp_server`

## npm / npx

This repo includes an npm wrapper so the server can be installed and run via `npx`.

### Build npm package (multi-platform binaries)

```bash
npm run build:npm
```

This creates platform binaries under `native/` and prepares the package for `npm pack`/publish.

### Run with npx

After publishing the package (or using a local tarball), you can run:

```bash
SERPER_API_KEY=your-key npx go-serper-mcp-server -t stdio
```

To run a specific version:

```bash
SERPER_API_KEY=your-key npx go-serper-mcp-server@1.0.0 -t stdio
```

For a local tarball:

```bash
npm pack
SERPER_API_KEY=your-key npx ./go-serper-mcp-server-*.tgz -t stdio
```

## Claude Code

```bash
claude mcp add --transport stdio serper -- npx -y go-serper-mcp-server -t stdio
```

```bash
claude mcp add serper --transport stdio --env SERPER_API_KEY=YOUR_KEY -- npx -y go-serper-mcp-server -t stdio
```

```bash
claude mcp add serper --transport stdio --scope user --env SERPER_API_KEY=YOUR_KEY -- npx -y go-serper-mcp-server -t stdio
```

In project `.mcp.json` or global `~/.claude.json`

```json
{
  "mcpServers": {
    "serper": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "go-serper-mcp-server", "-t", "stdio"],
      "env": {
        "SERPER_API_KEY": "${SERPER_API_KEY}"
      }
    }
  }
}
```

## Codex CLI

Codex supports MCP servers in `~/.codex/config.toml` or via the `codex mcp add` command.

Add via CLI:

```bash
codex mcp add serper -- npx -y go-serper-mcp-server -t stdio
```

Or configure in `~/.codex/config.toml`:

```toml
[mcp_servers.serper]
command = "npx"
args = ["-y", "go-serper-mcp-server", "-t", "stdio"]
env = { "SERPER_API_KEY" = "${SERPER_API_KEY}" }
```

## Cursor

- macOS/Linux: `~/.cursor/mcp.json`
- Windows: `%USERPROFILE%\\.cursor\\mcp.json`

```json
{
  "mcpServers": {
    "serper": {
      "command": "npx",
      "args": ["-y", "go-serper-mcp-server", "-t", "stdio"],
      "env": {
        "SERPER_API_KEY": "PASTE_YOUR_KEY_HERE"
      }
    }
  }
}
```

## MCP Client Config Example

```json
{
  "mcpServers": {
    "serper": {
      "command": "/path/to/go_serper_mcp_server",
      "args": ["-t", "stdio"],
      "env": {
        "SERPER_API_KEY": "your-key"
      }
    }
  }
}
```

![](https://asdertasd.site/counter/go_serper_mcp_server)