SerpApi MCP Server

A Model Context Protocol (MCP) server implementation that integrates with SerpApi for comprehensive search engine results and data extraction.

Features

• Multi-Engine Search: Google, Bing, Yahoo, DuckDuckGo, Yandex, Baidu, YouTube, eBay, Walmart, and more
• Real-time Weather Data: Location-based weather with forecasts via search queries
• Stock Market Data: Company financials and market data through search integration
• Dynamic Result Processing: Automatically detects and formats different result types
• Raw JSON Support: Option to return full unprocessed API responses
• Structured Results: Clean, formatted output optimized for AI consumption
• Rate Limit Handling: Automatic retry logic with exponential backoff
• Error Recovery: Comprehensive error handling and user feedback

Installation

git clone https://github.com/serpapi/mcp-server.git
cd mcp-server
uv sync

Configuration

Environment Variables

Required

• SERPAPI_API_KEY: Your SerpApi API key from serpapi.com/manage-api-key

Setup Steps

1. Get API Key: Sign up at SerpApi and get your API key
2. Create .env file:

   SERPAPI_API_KEY=your_api_key_here

3. Run Server:

   uv run src/server.py

Client Configurations

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "serpapi": {
      "command": "uv",
      "args": ["run", "/path/to/mcp-server/src/server.py"],
      "env": {
        "SERPAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

VS Code

Add to your VS Code settings or .vscode/mcp.json:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "apiKey",
      "description": "SerpApi API Key",
      "password": true
    }
  ],
  "servers": {
    "serpapi": {
      "command": "uv",
      "args": ["run", "src/server.py"],
      "env": {
        "SERPAPI_API_KEY": "${input:apiKey}"
      }
    }
  }
}

Cursor

For Cursor v0.48.6+, add to MCP Servers:

{
  "mcpServers": {
    "serpapi-mcp": {
      "command": "uv",
      "args": ["run", "src/server.py"],
      "env": {
        "SERPAPI_API_KEY": "YOUR-API-KEY"
      }
    }
  }
}

Available Tools

Universal Search Tool (search)

The consolidated search tool that handles all search types through a single interface.

Best for:

• Any type of search query (web, weather, stock, images, news, shopping)
• Unified interface across all search engines and result types
• Both formatted output and raw JSON responses

Parameters:

• params (Dict): Search parameters including:
  • q (str): Search query (required)
  • engine (str): Search engine (default: "google_light")
  • location (str): Geographic location filter
  • num (int): Number of results (default: 10)
• raw (bool): Return raw JSON response (default: false)

Usage Examples:

General Search

{
  "name": "search",
  "arguments": {
    "params": {
      "q": "best coffee shops",
      "engine": "google",
      "location": "Austin, TX"
    }
  }
}

Weather Search

{
  "name": "search",
  "arguments": {
    "params": {
      "q": "weather in London",
      "engine": "google"
    }
  }
}

Stock Market Search

{
  "name": "search",
  "arguments": {
    "params": {
      "q": "AAPL stock price",
      "engine": "google"
    }
  }
}

News Search

{
  "name": "search",
  "arguments": {
    "params": {
      "q": "latest AI developments",
      "engine": "google",
      "tbm": "nws"
    }
  }
}

Raw JSON Output

{
  "name": "search",
  "arguments": {
    "params": {
      "q": "machine learning",
      "engine": "google"
    },
    "raw": true
  }
}

Supported Search Engines

• Google (google) - Full Google search results
• Google Light (google_light) - Faster, lightweight Google results (default)
• Bing (bing) - Microsoft Bing search
• Yahoo (yahoo) - Yahoo search results
• DuckDuckGo (duckduckgo) - Privacy-focused search
• Yandex (yandex) - Russian search engine
• Baidu (baidu) - Chinese search engine
• YouTube (youtube_search) - Video search
• eBay (ebay) - Product search
• Walmart (walmart) - Product search

For a complete list, visit SerpApi Engines.

Result Types

The search tool automatically detects and formats different result types:

• Answer Box: Weather data, stock prices, knowledge graph, calculations
• Organic Results: Traditional web search results
• News Results: News articles with source and date
• Image Results: Images with thumbnails and links
• Shopping Results: Product listings with prices and sources

Results are prioritized and formatted for optimal readability.

Error Handling

The server provides comprehensive error handling:

• Rate Limiting: Automatic retry with exponential backoff
• Authentication: Clear API key validation messages
• Network Issues: Graceful degradation and error reporting
• Invalid Parameters: Helpful parameter validation

Common error responses:

{
  "error": "Rate limit exceeded. Please try again later."
}

Development

Running in Development Mode

# Install dependencies
uv sync

# Run with MCP Inspector
uv run mcp dev src/server.py

# Run server directly
uv run src/server.py

Project Structure

serpapi-mcp-server/
├── src/
│   └── server.py           # Main MCP server implementation
├── pyproject.toml         # Project configuration  
├── README.md              # This file
├── LICENSE               # MIT License
└── .env.example          # Environment template

Usage Examples

Basic Search

# Search for information
result = await session.call_tool("search", {
    "params": {
        "q": "MCP protocol documentation",
        "engine": "google"
    }
})

Weather Query

# Get weather information
weather = await session.call_tool("search", {
    "params": {
        "q": "weather in San Francisco with forecast",
        "engine": "google"
    }
})

Stock Information

# Get stock data
stock = await session.call_tool("search", {
    "params": {
        "q": "Tesla stock price and market cap",
        "engine": "google"
    }
})

Raw JSON Response

# Get full API response
raw_data = await session.call_tool("search", {
    "params": {
        "q": "artificial intelligence",
        "engine": "google"
    },
    "raw": True
})

Troubleshooting

Common Issues

"Invalid API key" Error:

• Verify your API key at serpapi.com/manage-api-key
• Check that SERPAPI_API_KEY is set in your environment

"Rate limit exceeded" Error:

• Wait for the retry period
• Consider upgrading your SerpApi plan
• Reduce request frequency

"Module not found" Error:

• Ensure dependencies are installed: uv install or pip install mcp serpapi python-dotenv
• Check Python version compatibility (3.13+ required)

"No results found" Error:

• Try adjusting your search query
• Use a different search engine
• Check if the query is valid for the selected engine

Contributing

1. Fork the repository
2. Create your feature branch: git checkout -b feature/amazing-feature
3. Install dependencies: uv install
4. Make your changes
5. Commit changes: git commit -m 'Add amazing feature'
6. Push to branch: git push origin feature/amazing-feature
7. Open a Pull Request

License

MIT License - see LICENSE file for details.