Metadata-Version: 2.4
Name: serper-toolkit
Version: 0.0.10
Summary: A high-performance, asynchronous MCP server for Serper Google Search, featuring connection pooling, request retries, and intelligent input parsing.
Author-email: "Joey.Kot" <joey.kot.x@gmail.com>
Keywords: serper,mcp,server,google,search
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.28.1
Requires-Dist: h2>=4.2.0
Requires-Dist: dotenv>=0.9.9
Requires-Dist: fastmcp>=2.14.4

# 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`.

```bash
# 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:

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

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

```Python
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:

```Python
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:

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

## License Agreement

This project is licensed under the MIT License.
