Content
# Search MCP Server
A search service implementation based on the MCP protocol, providing support for multiple search engines. Cursor and Claude Desktop can seamlessly integrate with it.
Developed in Python, it supports asynchronous processing and high-concurrency requests, currently offering three search engine options:
- Brave Search: A professional search interface service product from abroad.
- 秘塔（Metaso）search: A reverse implementation interface for Metaso AI search, unofficial interface.
- 博查（bocha）search: The search API product with the highest market share in the domestic Search API market.
For more knowledge about MCP, see AI全书 ([What is MCP (Large Model Context)? What is it used for? How to use it?](https://aibook.ren/archives/mcp-course))
**Author**: 凌封 (WeChat: fengin)
**Website**: [https://aibook.ren]() (AI全书)
## Usage Example
## Features
- **Multi-Search Engine Support**:
- Brave Search: Provides web search and location search
- Metaso Search: Offers 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 tool's content acquisition capabilities
- **Modular Design**: Each search engine is an independent module and can also be used separately in other locations
## Three Search Engine Options
<mark>Only one search engine can be effective at runtime</mark>. To help everyone choose which one to configure for deployment, I have listed a rough comparison below:
| 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 (Versions below this will cause issues connecting to the mcp server)
- Scientific Internet Access (Required only when using Brave Search)
#### 1.1 Install Browser Driver (Only for Metaso)
```
# Installing the Playwright Framework
pip install playwright>=1.35.0
# Install Browser Driver, Only Install Chromium
playwright install chromium
```
### 2. Download the Code
```bash
git clone https://github.com/fengin/search-server.git
```
### 3. Enable the Search Engine You Want
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 can also be configured through the environment variable SEARCH_ENGINE.
### 4. Configure the Corresponding Search Modules
There is a config.py file under each of the following module directories:
- src\search\proxy\brave
- src\search\proxy\metaso
- src\search\proxy\bocha
Modify the configuration in the corresponding config.py file based on your selection.
#### 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 = "The brave_api_key you applied for"
```
If you are using it in Claude Desktop, you can also configure this parameter through environment variables in Claude Desktop. However, 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:
- Magic (also needed 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 = "the metaso_uid you obtained"
METASO_SID = "the metaso_sid you obtained"
```
Similarly, Claude Desktop can configure environment variables through the MCP Servers settings;
**How to obtain uid and sid:**
Log into your account on the Secret Tower AI search ( <mark>It is recommended to log into 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: Currently, it is suspected that Secret Tower has a limit on the total number of search requests from a single IP address, so it is recommended to implement IP rotation</mark>
You can provide the uid-sid of multiple accounts and modify the relevant usage code with `,` to separate them. Each time a service request is made, one will be randomly selected from them, which I will consider further later.
#### 4.3 Bocha Configuration
```python
BOCHA_API_KEY = os.getenv("BOCHA_API_KEY", "")
if not BOCHA_API_KEY:
BOCHA_API_KEY="the bocha_api_key you applied for"
```
Registration application address: https://open.bochaai.com/
The usage is charged by the number of calls, which is not cheap, but the search quality is indeed quite good. I have a limited number of free trial codes; please 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 of the source code you pulled down.
#### 5.2 Claude Desktop Configuration
Locate the configuration file
**Method 1**
```
# widnows
C:\Users\{User}\AppData\Roaming\Claude\claude_desktop_config.json
# mac/linux should look in the user's home directory
```
**Method Two**
Open the Claude Desktop application and navigate to:
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, there's no need to configure this.
<mark>The cursor will pop up a black window, do not close it, do not close it</mark>, this is the running MCP Server process, and currently, there is no way to prevent it from appearing.
After configuring Claude Desktop, you must restart the application for the changes to take effect.
#### 5.4 Troubleshooting
Many people encounter issues after configuring the Cursor. Even after setting it up in the MCP Servers, the status still shows a red dot and "Tools Not Found," and it won't be called during use. This is because it hasn't been configured properly.
The most likely issues are:
1. The environment is not prepared, including the required software and version requirements. Please refer to the environment section for details.
2. The prepared environment is incorrect. For example, on Windows, there may be cmd terminal, powershell terminal, and possibly gitbash terminal. Open the cmd terminal (which is generally used for Cursor) to check the environment and run the command: `uv --directory D:\code\search-server run search`.
3. The configuration path/command is incorrect. You can open the terminal and run the command to check: `uv --directory D:\code\search-server run search`.
4. If you closed the black window, you need to restart Cursor when you open it again.
5. The Cursor version is too old.
6. If you encounter the following error during execution, it is because Chromium is not installed. Please refer to section 1.1 of the environment preparation for the 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 continue your normal work in your Claude Desktop or Cursor, and it will automatically call the search interface to retrieve content when necessary</mark>. For example, if you are organizing the technological development directions for 2025 as software content, it will call the search tool to gather information from the web:
- Once the tool is configured, it will recognize the presence of 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 according to the demand and call the search tool.
- Based on the content returned from the search, it will organize the results you need.
One thing to note is that <mark>in Cursor, the composer agent mode must be enabled for it to work</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 proxy
├── 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**
- Perform 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**
- Search for location-related information (businesses, restaurants, etc.)
- Input parameters:
- `query` (string): Location search keywords
- `count` (number, optional): Number of results (maximum 20)
- Automatically switch to web search when there are no relevant results
#### Metaso Search Engine
- **search**
- Perform web searches with multiple modes
- Input parameters:
- `query` (string): Search keywords
- `mode` (string, optional): Search mode
- `concise`: Concise mode, provides brief and to-the-point answers
- `detail`: Detailed mode, provides comprehensive and thorough answers (default)
- `research`: Research mode, provides in-depth analysis (<mark>currently not supported, reverse engineering was unsuccessful</mark>)
- **scholar_search**
- Perform academic searches, specifically for finding academic resources
- Input parameters:
- `query` (string): Academic search keywords
- `mode` (string, optional): Search mode, same as above
#### Bocha Search Engine
- **search**
- Perform 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
- Return 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)
