MCP Serp Server

You run an MCP server that talks to AceDataCloud to perform Google searches and return structured results. This enables you to perform web, image, news, video, places, maps, and knowledge-graph searches from any MCP-compatible client, with localization and time-filter capabilities.

How to use

You use an MCP client to connect to the Serp MCP server and issue search requests. The server supports multiple search types such as web, images, news, videos, places, and maps, and returns structured results that include knowledge graph data, direct answers, and related queries. To get started, obtain your API token, start the Serp server locally, and point your MCP client at the server. You can then perform targeted searches, specify a country and language for localization, and apply time filters to refine results.

How to install

# prerequisites: Python installed on your system

# Clone the server source (example URL shown in code block)
git clone https://github.com/AceDataCloud/mcp-serp.git
cd mcp-serp

# Install with dev dependencies
pip install -e .

# Optional: install with uv if you prefer the UVX runner
uv pip install -e .

Configuration and running the server

Prepare your environment to run the server by providing your API token. You will typically set up a local environment file and start the server using one of the supported run methods.

# Copy example environment file
cp .env.example .env

# Edit with your API token
echo "ACEDATACLOUD_API_TOKEN=your_token_here" > .env

Run the server

mcp-serp

# Or run directly with Python
python main.py

Environment variables and defaults

The following environment variables are used by the Serp MCP server. You should set them in your environment or in your .env file before starting the server.

ACEDATACLOUD_API_TOKEN=your_api_token_here
ACEDATACLOUD_API_BASE_URL=https://api.acedata.cloud
SERP_REQUEST_TIMEOUT=30
LOG_LEVEL=INFO

-Claude Desktop integration

If you use Claude Desktop, configure the MCP server by adding entries for the server under the mcpServers section in your Claude configuration. The following examples show how to wire the Serp MCP server using either the standard CLI or the uv runner.

{
  "mcpServers": {
    "serp": {
      "command": "mcp-serp",
      "env": {
        "ACEDATACLOUD_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Alternative run with UVX

{
  "mcpServers": {
    "serp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-serp", "mcp-serp"],
      "env": {
        "ACEDATACLOUD_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

What you can do with the server (tools overview)

The server exposes a suite of search and information tools that you can call from your MCP client. These tools enable flexible search queries, image lookups, news retrieval, video results, local place searches, map data, and knowledge graph information, all with localization and time-range filtering.

Troubleshooting and notes

If you run into authentication or timeout issues, verify that your API token is valid, the base URL is correct, and the server has network access to AceDataCloud. Ensure that the required environment variables are set in the environment or in your startup script. Check logs for any errors related to token validity, rate limits, or misconfigured transport.

Available tools

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

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