SerpMCP

# SerpMCP

<!-- mcp-name: io.github.AceDataCloud/mcp-serp -->

[![PyPI version](https://img.shields.io/pypi/v/mcp-serp.svg)](https://pypi.org/project/mcp-serp/)
[![PyPI downloads](https://img.shields.io/pypi/dm/mcp-serp.svg)](https://pypi.org/project/mcp-serp/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for Google search using [SERP API](https://platform.acedata.cloud/documents/44c86226-8eaa-49bf-85f3-1fae8d2e23f1) through the [AceDataCloud API](https://platform.acedata.cloud).

Perform Google searches and get structured results directly from Claude, VS Code, or any MCP-compatible client.

## Features

- **Web Search** - Regular Google web search with structured results
- **Image Search** - Search for images with URLs and thumbnails
- **News Search** - Get latest news articles on any topic
- **Video Search** - Find videos from YouTube and other sources
- **Places Search** - Search for local businesses and places
- **Maps Search** - Find locations and geographic information
- **Knowledge Graph** - Get structured entity information
- **Localization** - Support for multiple countries and languages
- **Time Filtering** - Filter results by time range

## Tool Reference

| Tool | Description |
|------|-------------|
| `serp_google_search` | Search Google and get structured results using the SERP API. |
| `serp_google_images` | Search Google Images and get image results. |
| `serp_google_news` | Search Google News and get news article results. |
| `serp_google_videos` | Search Google Videos and get video results. |
| `serp_google_places` | Search Google for local places and businesses. |
| `serp_google_maps` | Search Google Maps for locations. |
| `serp_list_search_types` | List all available Google search types. |
| `serp_list_countries` | List commonly used country codes for Google search. |
| `serp_list_languages` | List commonly used language codes for Google search. |
| `serp_list_time_ranges` | List available time range filters for Google search. |
| `serp_get_usage_guide` | Get a comprehensive guide for using the Google SERP tools. |

## Quick Start

### 1. Get Your API Token

1. Sign up at [AceDataCloud Platform](https://platform.acedata.cloud)
2. Go to the [API documentation page](https://platform.acedata.cloud/documents/44c86226-8eaa-49bf-85f3-1fae8d2e23f1)
3. Click **"Acquire"** to get your API token
4. Copy the token for use below

### 2. Use the Hosted Server (Recommended)

AceDataCloud hosts a managed MCP server — **no local installation required**.

**Endpoint:** `https://serp.mcp.acedata.cloud/mcp`

All requests require a Bearer token. Use the API token from Step 1.

#### Claude.ai

Connect directly on [Claude.ai](https://claude.ai) with OAuth — **no API token needed**:

1. Go to Claude.ai **Settings → Integrations → Add More**
2. Enter the server URL: `https://serp.mcp.acedata.cloud/mcp`
3. Complete the OAuth login flow
4. Start using the tools in your conversation

#### Claude Desktop

Add to your config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "serp": {
      "type": "streamable-http",
      "url": "https://serp.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}
```

#### Cursor / Windsurf

Add to your MCP config (`.cursor/mcp.json` or `.windsurf/mcp.json`):

```json
{
  "mcpServers": {
    "serp": {
      "type": "streamable-http",
      "url": "https://serp.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}
```

#### VS Code (Copilot)

Add to your VS Code MCP config (`.vscode/mcp.json`):

```json
{
  "servers": {
    "serp": {
      "type": "streamable-http",
      "url": "https://serp.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}
```

Or install the [Ace Data Cloud MCP extension](https://marketplace.visualstudio.com/items?itemName=acedatacloud.acedatacloud-mcp) for VS Code, which registers the hosted MCP servers with one-click setup.

#### JetBrains IDEs

1. Go to **Settings → Tools → AI Assistant → Model Context Protocol (MCP)**
2. Click **Add** → **HTTP**
3. Paste:

```json
{
  "mcpServers": {
    "serp": {
      "url": "https://serp.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}
```


#### Claude Code

Claude Code supports MCP servers natively:

```bash
claude mcp add serp --transport http https://serp.mcp.acedata.cloud/mcp \
  -h "Authorization: Bearer YOUR_API_TOKEN"
```

Or add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "serp": {
      "type": "streamable-http",
      "url": "https://serp.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}
```

#### Cline

Add to Cline's MCP settings (`.cline/mcp_settings.json`):

```json
{
  "mcpServers": {
    "serp": {
      "type": "streamable-http",
      "url": "https://serp.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}
```

#### Amazon Q Developer

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "serp": {
      "type": "streamable-http",
      "url": "https://serp.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}
```

#### Roo Code

Add to Roo Code MCP settings:

```json
{
  "mcpServers": {
    "serp": {
      "type": "streamable-http",
      "url": "https://serp.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}
```

#### Continue.dev

Add to `.continue/config.yaml`:

```yaml
mcpServers:
  - name: serp
    type: streamable-http
    url: https://serp.mcp.acedata.cloud/mcp
    headers:
      Authorization: "Bearer YOUR_API_TOKEN"
```

#### Zed

Add to Zed's settings (`~/.config/zed/settings.json`):

```json
{
  "language_models": {
    "mcp_servers": {
      "serp": {
        "url": "https://serp.mcp.acedata.cloud/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_API_TOKEN"
        }
      }
    }
  }
}
```

#### cURL Test

```bash
# Health check (no auth required)
curl https://serp.mcp.acedata.cloud/health

# MCP initialize
curl -X POST https://serp.mcp.acedata.cloud/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
```

### 3. Or Run Locally (Alternative)

If you prefer to run the server on your own machine:

```bash
# Install from PyPI
pip install mcp-serp
# or
uvx mcp-serp

# Set your API token
export ACEDATACLOUD_API_TOKEN="your_token_here"

# Run (stdio mode for Claude Desktop / local clients)
mcp-serp

# Run (HTTP mode for remote access)
mcp-serp --transport http --port 8000
```

#### Claude Desktop (Local)

```json
{
  "mcpServers": {
    "serp": {
      "command": "uvx",
      "args": ["mcp-serp"],
      "env": {
        "ACEDATACLOUD_API_TOKEN": "your_token_here"
      }
    }
  }
}
```

#### Docker (Self-Hosting)

```bash
docker pull ghcr.io/acedatacloud/mcp-serp:latest
docker run -p 8000:8000 ghcr.io/acedatacloud/mcp-serp:latest
```

Clients connect with their own Bearer token — the server extracts the token from each request's `Authorization` header.

## Available Tools

### Search Tools

| Tool                 | Description                             |
| -------------------- | --------------------------------------- |
| `serp_google_search` | Flexible Google search with all options |
| `serp_google_images` | Search for images                       |
| `serp_google_news`   | Search for news articles                |
| `serp_google_videos` | Search for videos                       |
| `serp_google_places` | Search for local places/businesses      |
| `serp_google_maps`   | Search for map locations                |

### Information Tools

| Tool                     | Description                          |
| ------------------------ | ------------------------------------ |
| `serp_list_search_types` | List available search types          |
| `serp_list_countries`    | List country codes for localization  |
| `serp_list_languages`    | List language codes for localization |
| `serp_list_time_ranges`  | List time range filter options       |
| `serp_get_usage_guide`   | Get comprehensive usage guide        |

## Usage Examples

### Basic Web Search

```
User: Search for information about artificial intelligence

Claude: I'll search for information about AI.
[Calls serp_google_search with query="artificial intelligence"]
```

### News Search with Time Filter

```
User: What's the latest news about technology?

Claude: I'll search for recent tech news.
[Calls serp_google_news with query="technology", time_range="qdr:d"]
```

### Localized Search

```
User: Find popular restaurants in Tokyo

Claude: I'll search for restaurants in Tokyo.
[Calls serp_google_places with query="popular restaurants Tokyo", country="jp"]
```

### Image Search

```
User: Find images of the Northern Lights

Claude: I'll search for aurora borealis images.
[Calls serp_google_images with query="Northern Lights aurora borealis"]
```

## Search Parameters

### Search Types

| Type     | Description                  |
| -------- | ---------------------------- |
| `search` | Regular web search (default) |
| `images` | Image search                 |
| `news`   | News articles                |
| `m