serper-toolkit 0.0.10

A high-performance, asynchronous MCP server for Serper Google Search, featuring connection pooling, request retries, and intelligent input parsing.

Serper MCP Toolkit

A high-performance, asynchronous MCP server that provides comprehensive Google search and web content scraping capabilities through the Serper API (excluding some rarely used interfaces).

This project is built on httpx, utilizing asynchronous clients and connection pool management to offer LLMs a stable and efficient external information retrieval tool.

Key Features

• Asynchronous Architecture: Fully based on asyncio and httpx, ensuring high throughput and non-blocking I/O operations.
• HTTP Connection Pool: Manages and reuses TCP connections through a global httpx.AsyncClient instance, significantly improving performance under high concurrency.
• Concurrency Control: Built-in global and per-API endpoint concurrency semaphores effectively manage API request rates to prevent exceeding rate limits.
• Automatic Retry Mechanism: Integrated request retry functionality with exponential backoff strategy automatically handles temporary network fluctuations or server errors, enhancing service stability.
• Intelligent Country Code Parsing: Includes a comprehensive country name dictionary supporting inputs in Chinese, English, ISO Alpha-2/3, and other formats, with automatic normalization.
• Flexible Environment Variable Configuration: Supports fine-tuned service configuration via environment variables.

Available Tools

This service provides the following tools:

Tool Name	Description
serper-general-search	Performs general Google web searches.
serper-image-search	Performs Google image searches.
serper-video-search	Performs Google video searches.
serper-place-search	Performs Google place searches.
serper-maps_search	Performs Google Maps searches.
serper-news-search	Performs Google news searches.
serper-lens-search	Performs Google Lens reverse image searches via image URL.
serper-scholar-search	Performs Google Scholar searches.
serper-shopping-search	Performs Google Shopping searches.
serper-patents-search	Performs Google Patents searches.
serper-scrape	Scrapes and returns the content of a specified URL.

Installation Guide

It is recommended to install using pip or uv.

# Using pip
pip install serper-toolkit

# Or using uv
uv pip install serper-toolkit

Quick Start

Set Environment Variables

Create a .env file in the project root directory and enter your Serper API key:

Environment Variables	Default value	Description
SERPER_API_KEY	xxx	your-serper-api-key-here
SERPER_HTTP2	0	Disable or enable HTTP2, <0/1>
SERPER_MAX_WORKERS	10	Number of processes
SERPER_MAX_CONNECTIONS	200	Maximum number of connections
SERPER_MAX_CONCURRENT_REQUESTS	200	Maximum number of concurrent requests
SERPER_KEEPALIVE	20	Maximum number of concurrent connections
SERPER_RETRY_COUNT	3	Maximum number of retries
SERPER_RETRY_BASE_DELAY	0.5	Base delay time for retries in seconds
SERPER_ENDPOINT_CONCURRENCY	{"search":10,"scrape":2}	Set concurrency per endpoint (JSON format)
SERPER_ENDPOINT_RETRYABLE	{"scrape": false}	Set retry allowance per endpoint (JSON format)
SERPER_MCP_ENABLE_STDIO	0	Disable or enable STDIO, <0/1>
SERPER_MCP_ENABLE_HTTP	0	Disable or enable HTTP, <0/1>
SERPER_MCP_ENABLE_SSE	0	Disable or enable SSE, <0/1>
SERPER_MCP_HTTP_HOST	127.0.0.1	HTTP host address
SERPER_MCP_HTTP_PORT	7001	HTTP host port
SERPER_MCP_SSE_HOST	127.0.0.1	SSE host address
SERPER_MCP_SSE_PORT	7001	SSE host port
SERPER_MCP_LOCK_FILE	/tmp/serper_mcp.lock	Lock file path

• STDIO, HTTP, and SSE can only be used one at a time. If you need to use multiple protocols, please start separate services for each.
• When using multiple services, please specify different lock files for each.

Configure MCP Client

Add the following server configuration in the MCP client configuration file:

{
  "mcpServers": {
    "serper": {
      "command": "python3",
      "args": ["-m", "serper-toolkit"],
      "env": {
        "SERPER_API_KEY": "<Your Serper API key>"
      }
    }
  }
}

{
  "mcpServers": {
    "serper-toolkit": {
      "command": "uvx",
      "args": ["serper-toolkit"],
      "env": {
        "SERPER_API_KEY": "<Your Serper API key>"
      }
    }
  }
}

Tool Parameters and Usage Examples

serper-general-search: Perform general web search

Parameters:

• search_key_words (str, required): Keywords to search.
• search_country (str, optional): Specify the country/region for search results. Supports Chinese names (e.g., "China"), English names (e.g., "United States"), or ISO codes (e.g., "US"). Default is "US".
• search_num (int, optional): Number of results to return, range 1-100. Default is 10.
• search_time (str, optional): Filter results by time range. Available values: "hour", "day", "week", "month", "year".

Example:

result_json = serper_general_search(
    search_key_words="AI advancements 2024",
    search_country="United States",
    search_num=5,
    search_time="month"
)

serper-lens-search: Perform reverse image search via image URL

Parameters:

• image_url (str, required): Public URL of the image to search.
• search_country (str, optional): Specify the country/region for search results. Default is "US".

Example:

result_json = serper_lens_search(
    image_url="https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png",
    search_country="JP"
)

serper-scrape: Scrape webpage content

Parameters:

• url (str, required): URL of the target webpage.
• include_markdown (bool, optional): Whether to include Markdown-formatted content in the returned results. Default is False.

Example:

result_json = serper_scrape(
    url="https://www.example.com",
    include_markdown=True
)

License Agreement

This project is licensed under the MIT License.