Content
# Search MCP Server
A search service implementation based on the MCP protocol, providing support for multiple search engines, seamlessly integrated with Cursor and Claude Desktop.
Developed in Python, it supports asynchronous processing and high concurrency requests. Currently, it supports three search engine options:
- Brave Search: A foreign company specializing in providing search interface services.
- Metaso Search: A reverse-engineered interface of Metaso AI Search, an unofficial interface.
- Bocha Search: The search API product with the highest market share in China's Search API market.
For more MCP knowledge, see AI Book ([What is MCP (Large Model Context) and 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
- **Multiple Search Engine Support**:
- Brave Search: Provides web search and location search
- Metaso Search: Provides web search and academic search, supporting both concise and in-depth 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 tool.
- **Modular Design**: Each search engine is an independent module and can be copied and used elsewhere.
## Selection of Three Search Engines
<mark>Only one search engine can be active at runtime</mark>. To make it easier for everyone to choose which one to configure online, I have listed a rough comparison:
| Search Engine | Domestic/Foreign | VPN Required | Summary Included | 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 | Very Fast | Low |
## Installation and Usage
### 1. Environment Requirements
- Python 3.10+
- uv 0.24.0+
- node.js v20.15.0
- cursor >=0.45.10 (Older versions may have connection issues with the MCP server)
- VPN (Only required for Brave Search)
#### 1.1 Install Browser Driver (Only required 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, respectively. You can also configure the environment variable SEARCH_ENGIN.
### 4. Configure the Corresponding Search Module
Each of the following three module directories has a corresponding config.py file:
- src\search\proxy\brave
- src\search\proxy\metaso
- src\search\proxy\bocha
Based on your selection, modify the corresponding config.py file configuration.
#### 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 brave_api_key"
```
If you are using it in Claude Desktop, you can also configure it in Claude Desktop by passing this parameter through environment variables, but Cursor currently does not support environment variables, so you can only modify it 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>, requiring:
- VPN (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 metaso_uid"
METASO_SID = "Your metaso_sid"
```
Similarly, Claude Desktop usage can be configured through environment variables in MCP Servers;
**How to obtain uid and sid:**
Enter Metaso AI Search, log in to your account (<mark>it is recommended to log in to your account, otherwise you may encounter strange restrictions</mark>), then press F12 to open the developer tools, and find the values of `uid` and `sid` from Application > Cookies.
**Multiple Account Access**
<mark>Note: It is currently suspected that Metaso has a limit on the total number of searches for IP addresses. It is recommended to add IP rotation</mark>
You can provide the uid-sid of multiple accounts and use `,` to modify the relevant usage code. The service will select one of them for each request. I will consider this later.
#### 4.3 Bocha Configuration
```python
BOCHA_API_KEY = os.getenv("BOCHA_API_KEY", "")
if not BOCHA_API_KEY:
BOCHA_API_KEY="Your bocha_api_key"
```
Registration application address: https://open.bochaai.com/
Calls are charged by the number of times, which is not cheap, but the search quality is indeed better. I have a small amount of free trial codes. Contact me via WeChat if you need them;
### 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 down the source code.
#### 5.2 Claude Desktop Configuration
Find the configuration file
**Method 1**
```
# widnows
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 and enter to view:
Claude Desktop—>Menu—>Settings—>Developer—>Edit Config
Edit and add the following MCP Server:
```json
{
"mcpServers": {
"search": {
"command": "uv",
"args": [
"--directory",
"D:\\code\\search-server",
"run",
"search"
],
"env": {
"BRAVE_API_KEY": "Your API KEY"
}
}
}
}
```
Environment variables depend on your needs. If the code has been changed, there is no need to configure this.
<mark>A black window will pop up in Cursor, do not close it, do not close it</mark>. This is the MCP Server process that is started. There is currently no way to prevent it from popping up.
Be sure to restart the application for the Claude Desktop configuration to take effect.
#### 5.4 Troubleshooting
Many people encounter this after configuring Cursor. After configuring in MCP Servers, the status still shows a red dot, Tools Not Found, and it will not be called when used. This is because it is not configured properly.
Most possible situations are:
1. The environment is not ready, including the required software and version requirements. See the environment chapter for details.
2. The prepared environment is incorrect. For example, Windows has cmd terminal, powershell terminal, and may have gitbash terminal installed. Open the cmd terminal (cursor is generally this) and check the environment. Run uv --directory D:\code\search-server run search directly.
3. The configuration path/command is incorrect. You can open the terminal and run the command to see: uv --directory D:\code\search-server run search
4. The black window is closed. To open it again, you need to restart Cursor.
5. The Cursor version is too old.
6. The following error is reported during runtime, because chromium is not installed. See environment preparation 1.1 for the solution.
```shell
错误:搜索执行错误:BrowserType.launch persistent context:Executable doesn't exist atC:\Users\fengi\AppDatalLocal\ms-playwright\chromium headless shell-1155\chrome-winlheadless shell.exe
```
### 6. Usage
<mark>Just do your normal work directly in your Claude Desktop or Cursor, and it will automatically call the search interface to get content when necessary</mark>. For example, if you organize the technical development directions in 2025 on the Internet as software content, it will call the search tool to get network information:
- After configuring the tool, its information will know that there is this tool.
- According to your requirements, it will automatically analyze and judge that the search tool needs to be used.
- According to the needs, extract keywords and call the search tool.
- According to the search return content, organize the results you want.
One thing to note is that <mark>in Cursor, you must enable the composer's agent mode to work for it to take effect</mark>. When calling the tool, you also need to click to execute it;
## Technical Details
### Project Structure
```shell
search/
├── __init__.py
├── server.py # MCP server implementation
└── proxy/ # Search engine proxy
├── brave/ # Brave search module
│ ├── __init__.py
│ ├── client.py # Core client implementation
│ ├── config.py # Configuration and rate limiting
│ └── exceptions.py # Exception definition
├── metaso/ # Metaso search module
│ ├── __init__.py
│ ├── client.py # Core client implementation
│ ├── config.py # Configuration and rate limiting
│ └── exceptions.py # Exception definition
├── bocha/ # Bocha search module
│ ├── __init__.py
│ ├── client.py # Core client implementation
│ ├── config.py # Configuration and rate limiting
│ └── exceptions.py # Exception definition
├── 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**
- Performs 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 when there are no relevant results
#### Metaso Search Engine
- **search**
- Performs web search, supporting multiple modes
- Input parameters:
- `query` (string): Search keywords
- `mode` (string, optional): Search mode
- `concise`: Concise mode, answers are short and refined
- `detail`: In-depth mode, answers are detailed and comprehensive (default)
- `research`: Research mode, answers are in-depth analysis (<mark>currently not supported, reverse engineering failed</mark>)
- **scholar_search**
- Performs 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**
- Performs 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
- Return content:
- Search statistics (total number of results, current page/total number of pages, number of results on this page)
- Web search results (title, URL, source, summary, publication time)
- Related image information (size, source, URL)
