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:

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)

go run . -t stdio

SSE

go run . -t sse -p 8894

SSE endpoint:

http://localhost:8894/sse

Build

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)

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:

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

To run a specific version:

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

For a local tarball:

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

Claude Code

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

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

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

{
  "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:

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

Or configure in ~/.codex/config.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

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

MCP Client Config Example

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