Content
# Search MCP Server
An implementation of a search service based on the MCP protocol, providing support for multiple search engines. Cursor and Claude Desktop can seamlessly integrate with it.
Developed using Python, it supports asynchronous processing and high concurrency requests. Currently, it supports three search engine options:
- Brave Search: A foreign company that specializes in providing search API services.
- Metaso Search: A reverse implementation interface of Metaso AI search, an unofficial interface.
- Bocha Search: The most popular search API product in the domestic Search API market.
For more knowledge about MCP, see AI Book ([What is MCP (Large Model Context)? What is it used for? How to use it?](https://aibook.ren/archives/mcp-course))
**Author**: Ling Feng (WeChat: fengin)
**Website**: [https://aibook.ren]() (AI Book)
## Usage Example
## Features
- **Multi-search engine support**:
- Brave Search: Provides web search and location search.
- Metaso Search: Provides web search and academic search, supporting both concise and detailed modes.
- Bocha Search: Provides web search, supporting time range filtering, detailed summaries, and image search.
- **Applicable scenarios**: Seamless integration with Claude Desktop or Cursor, greatly expanding the content acquisition capabilities of the tools.
- **Modular design**: Each search engine is an independent module and can also be copied for use elsewhere.
## Choice of Three Searches
<mark>Only one search engine can be effective at runtime</mark>. To facilitate everyone's choice of which one to configure, I have listed a rough comparison:
| Search Engine | Domestic/Foreign | Requires Magic | Built-in Summary | Quality | Free | Official | Speed | Registration Threshold |
| -------------- | ---------------- | -------------- | ---------------- | ------- | ---- | -------- | ----- | --------------------- |
| Brave | Foreign | Yes | No | High | Yes (limited) | Yes | Medium | Very High |
| Metaso | Domestic | No | Yes | Medium | Yes | No | Slow (AI Summary) | Low |
| Bocha | Domestic | No | No | High | No | Yes | Extremely Fast | Low |
## Installation and Usage
### 1. Environment Requirements
- Python 3.10+
- uv 0.24.0+
- node.js v20.15.0
- cursor >=0.45.10 (below this version, the MCP server configuration often fails to connect)
- Scientific Internet Access (only required for using Brave Search)
#### 1.1 Install Browser Driver (only for Metaso)
```
# Install Playwright framework
pip install playwright>=1.35.0
# Install browser driver, only install chromium
playwright install chromium
```
### 2. Download Code
```bash
git clone https://github.com/fengin/search-server.git
```
### 3. Enable Your Desired Search Engine
Open the project root directory and modify the following code in server.py to select the type to enable:
```python
# Search engine configuration
SEARCH_ENGINE = os.getenv("SEARCH_ENGINE", "bocha")
```
The values correspond to brave, metaso, and bocha, and you can also configure the environment variable SEARCH_ENGINE.
### 4. Configure the Corresponding Search Module
Each of the following three module directories contains a config.py file:
- src\search\proxy\brave
- src\search\proxy\metaso
- src\search\proxy\bocha
Modify the corresponding config.py file configuration based on your choice.
#### 4.1 Brave Search Configuration
```python
# Check API key
BRAVE_API_KEY = os.getenv("BRAVE_API_KEY")
if not BRAVE_API_KEY:
BRAVE_API_KEY = "Your applied brave_api_key"
```
If used in Claude Desktop, you can also configure this parameter through environment variables in Claude Desktop, but Cursor currently does not support environment variables and can only be modified in this file.
API KEY application address: [Brave Search - API](https://api-dashboard.search.brave.com/login)
<mark>The application threshold is relatively high</mark>, requirements include:
- Magic (also required during use)
- Email verification
- Credit card (can use a virtual one: [https://cardgenerator.org/](https://cardgenerator.org/))
#### 4.2 Metaso Configuration
```python
# Authentication information
METASO_UID = os.getenv("METASO_UID")
METASO_SID = os.getenv("METASO_SID")
if not METASO_UID or not METASO_SID:
METASO_UID = "Your obtained metaso_uid"
METASO_SID = "Your obtained metaso_sid"
```
Similarly, for Claude Desktop usage, you can configure environment variables in the MCP Servers configuration.
**How to obtain uid and sid:**
Log into your account on Metaso AI Search (it is recommended to log in, otherwise you may encounter strange restrictions), then open the developer tools with F12, and find the values of `uid` and `sid` from Application > Cookies.
**Multiple Account Access**
<mark>Note: Currently, it is suspected that Metaso has a limit on the total number of searches per IP address, so it is recommended to use IP rotation.</mark>
You can provide multiple accounts' uid-sid and modify the relevant usage code using `,`. Each time a request is made, one will be selected from them, which I will consider later.
#### 4.3 Bocha Configuration
```python
BOCHA_API_KEY = os.getenv("BOCHA_API_KEY", "")
if not BOCHA_API_KEY:
BOCHA_API_KEY = "Your applied bocha_api_key"
```
Registration application address: https://open.bochaai.com/
Charges are based on usage, which is not cheap, but the search quality is indeed quite good. I have a small number of free trial codes available; please contact me via WeChat if needed.
### 5. AI Tool Configuration
#### 5.1 Configuration in Cursor
- name: search
- type: cmd
- command: uv --directory D:\\code\\search-server run search
Where “D:\code\search-server” is the directory where you pulled the source code.
#### 5.2 Configuration in Claude Desktop
Find the configuration file:
**Method 1**
```
# Windows
C:\Users\{User}\AppData\Roaming\Claude\claude_desktop_config.json
# Mac/Linux should be found in the user's home directory
```
**Method 2**
Open the Claude Desktop application to view:
Claude Desktop → Menu → Settings → Developer → Edit Config
Edit to add the following MCP Server:
```json
{
"mcpServers": {
"search": {
"command": "uv",
"args": [
"--directory",
"D:\\code\\search-server",
"run",
"search"
],
"env": {
"BRAVE_API_KEY": "Your applied API KEY"
}
}
}
}
```
The environment variables depend on your needs; if the code has changed, this configuration may not be necessary.
<mark>Cursor will pop up a black window; do not close it.</mark> This is the process of the started MCP Server, and currently, there is no way to prevent it from popping up.
Make sure to restart the Claude Desktop application for the configuration to take effect.
#### 5.4 Troubleshooting
After configuring Cursor, many people encounter issues where the status shows a red dot in MCP Servers, indicating Tools Not Found, and it will not call during use. This is because it has not been configured properly.
Most likely issues include:
1. The environment is not prepared, including required software and version requirements; see the environment section for details.
2. The prepared environment is incorrect; for example, Windows has cmd terminal, PowerShell terminal, and possibly gitbash terminal. Open the cmd terminal (which is generally used by Cursor) to check the environment and run `uv --directory D:\code\search-server run search` directly.
3. The configuration path/command is incorrect; you can open the terminal to run the command and check: `uv --directory D:\code\search-server run search`.
4. If the black window is closed, you need to restart Cursor to open it again.
5. Cursor version is too old.
6. If you encounter the following error during runtime, it is because Chromium is not installed. See section 1.1 in the environment preparation for a solution.
```shell
Error: Search execution error: BrowserType.launch persistent context: Executable doesn't exist at C:\Users\fengi\AppData\Local\ms-playwright\chromium headless shell-1155\chrome-win\headless shell.exe
```
### 6. Usage
<mark>Just work normally in your Claude Desktop or Cursor, and when necessary, it will automatically call the search interface to obtain content.</mark> For example, if you organize the technological development directions for software in 2025, it will call the search tool to gather information from the web:
- After configuring the tool, it will know about this tool in its information.
- Based on your requirements, it will automatically analyze and determine the need to use the search tool.
- It will extract keywords based on the demand and call the search tool.
- It will organize the results you need based on the content returned from the search.
One thing to note is that <mark>in Cursor, the composer agent mode must be enabled for it to take effect</mark>, and you also need to click to execute when calling the tool.
## Technical Insights
### Project Structure
```shell
search/
├── __init__.py
├── server.py # MCP server implementation
└── proxy/ # Search engine proxies
├── brave/ # Brave search module
│ ├── __init__.py
│ ├── client.py # Core client implementation
│ ├── config.py # Configuration and rate limiting
│ └── exceptions.py # Exception definitions
├── metaso/ # Metaso search module
│ ├── __init__.py
│ ├── client.py # Core client implementation
│ ├── config.py # Configuration and rate limiting
│ └── exceptions.py # Exception definitions
├── bocha/ # Bocha search module
│ ├── __init__.py
│ ├── client.py # Core client implementation
│ ├── config.py # Configuration and rate limiting
│ └── exceptions.py # Exception definitions
├── brave_search.py # Brave MCP tool implementation
├── metaso_search.py # Metaso MCP tool implementation
└── bocha_search.py # Bocha search MCP tool implementation
```
### Interface Parameters
#### Brave Search Engine
- **search**
- Executes a web search, supporting pagination and filtering.
- Input parameters:
- `query` (string): Search keywords.
- `count` (number, optional): Number of results per page (maximum 20).
- `offset` (number, optional): Pagination offset (maximum 9).
- **location_search**
- Searches for location-related information (businesses, restaurants, etc.).
- Input parameters:
- `query` (string): Location search keywords.
- `count` (number, optional): Number of results (maximum 20).
- Automatically switches to web search if no relevant results are found.
#### Metaso Search Engine
- **search**
- Executes a web search, supporting multiple modes.
- Input parameters:
- `query` (string): Search keywords.
- `mode` (string, optional): Search mode.
- `concise`: Concise mode, providing short and refined answers.
- `detail`: Detailed mode, providing comprehensive answers (default).
- `research`: Research mode, providing in-depth analysis (<mark>currently not supported, reverse implementation has not succeeded</mark>).
- **scholar_search**
- Executes an academic search, specifically for finding academic resources.
- Input parameters:
- `query` (string): Academic search keywords.
- `mode` (string, optional): Search mode, same as above.
#### Bocha Search Engine
- **search**
- Executes a web search, supporting time range filtering and detailed summaries.
- Input parameters:
- `query` (string): Search keywords.
- `count` (number, optional): Number of results (1-10, default 10).
- `page` (number, optional): Page number, starting from 1.
- `freshness` (string, optional): Time range.
- `noLimit`: No time limit (default).
- `oneDay`: Within one day.
- `oneWeek`: Within one week.
- `oneMonth`: Within one month.
- `oneYear`: Within one year.
- `summary` (boolean, optional): Whether to display detailed summaries, default false.
- Returned content:
- Search statistics (total number of results, current page/total pages, number of results on this page).
- Web search results (title, URL, source, summary, publication time).
- Related image information (size, source, URL).
