Search Engines Proxy MCP server

This MCP server allows you to integrate search capabilities with AI tools like Cursor and Claude Desktop, supporting Brave Search, Metaso, and Bocha search engines. It acts as a bridge between your AI assistant and the web, enabling real-time information retrieval during conversations.

Installation Requirements

Prerequisites

• Python 3.10+
• uv 0.24.0+
• Node.js v20.15.0
• Cursor >=0.45.10
• VPN access (only required for Brave Search)

Browser Driver Setup (for Metaso only)

If you plan to use Metaso search, you'll need to install the browser driver:

# Install Playwright framework
pip install playwright>=1.35.0
# Install Chromium browser driver
playwright install chromium

Getting the Code

Clone the repository to your local machine:

git clone https://github.com/fengin/search-server.git

Configuration

Select Your Search Engine

Open server.py in the project root directory and modify the search engine setting:

# Search engine configuration
SEARCH_ENGINE = os.getenv("SEARCH_ENGINE", "bocha")

Available values: brave, metaso, or bocha. You can also set this via the SEARCH_ENGINE environment variable.

Configure Your Selected Search Engine

Brave Search Configuration

Navigate to src/search/proxy/brave/config.py and add your API key:

# Check API key
BRAVE_API_KEY = os.getenv("BRAVE_API_KEY")
if not BRAVE_API_KEY:
    BRAVE_API_KEY = "your_brave_api_key"

API keys can be obtained at Brave Search API. Note that registration requires email verification and credit card information.

Metaso Configuration

Navigate to src/search/proxy/metaso/config.py:

# Authentication info
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"

To get your UID and SID:

1. Log in to Metaso AI Search
2. Open developer tools (F12)
3. Go to Application > Cookies
4. Copy the values for uid and sid

Bocha Configuration

Navigate to src/search/proxy/bocha/config.py:

BOCHA_API_KEY = os.getenv("BOCHA_API_KEY", "")
if not BOCHA_API_KEY:
    BOCHA_API_KEY = "your_bocha_api_key"

Register for an API key at https://open.bochaai.com/.

Setting Up AI Tools

Cursor Configuration

1. Go to Settings > MCP Servers

2. Add a new server with these settings:

   • Name: search
   • Type: cmd
   • Command: uv --directory D:\code\search-server run search

   (Replace D:\code\search-server with your actual directory path)

Claude Desktop Configuration

Edit the Claude Desktop configuration file:

File location:

• Windows: C:\Users\{username}\AppData\Roaming\Claude\claude_desktop_config.json
• Mac/Linux: Located in your home directory

Alternatively, open Claude Desktop → Settings → Developer → Edit Config

Add the following to your configuration:

{
  "mcpServers": {
    "search": {
      "command": "uv",
      "args": [
        "--directory",
        "D:\\code\\search-server",
        "run",
        "search"
      ],
      "env": {
        "BRAVE_API_KEY": "your_api_key"
      }
    }
  }
}

Important: Restart Claude Desktop for changes to take effect.

Troubleshooting

If your MCP server shows "Tools Not Found" (red dot) in Cursor:

1. Verify you have all required software installed with correct versions
2. Test the command in a terminal: uv --directory D:\code\search-server run search
3. Don't close the black terminal window that appears in Cursor
4. Ensure your Cursor version is up-to-date
5. If using Metaso and getting errors about missing executable, install Chromium as described above

Using the Search Server

Once properly configured, your AI assistant will automatically use the search tool when needed. No manual commands are required - the AI will:

1. Determine when to use the search tool based on your requests
2. Extract relevant search keywords
3. Call the search engine
4. Integrate search results into responses

Note for Cursor users: You must enable the Composer agent mode for the search tool to work, and you'll need to approve tool execution when prompted.

Available Search Functions

Brave Search

• search: Web search with pagination support
  • Parameters: query, count (max 20), offset (max 9)
• location_search: Location-based searches
  • Parameters: query, count (max 20)

Metaso Search

• search: Web search with multiple modes
  • Parameters: query, mode (concise/detail)
• scholar_search: Academic research search
  • Parameters: query, mode (concise/detail)

Bocha Search

• search: Web search with time filters and detailed summaries
  • Parameters: query, count (1-10), page, freshness (noLimit/oneDay/oneWeek/oneMonth/oneYear), summary (boolean)

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "search" '{"command":"uv","args":["--directory","D:\\code\\search-server","run","search"],"env":[]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "search": {
            "command": "uv",
            "args": [
                "--directory",
                "D:\\code\\search-server",
                "run",
                "search"
            ],
            "env": []
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "search": {
            "command": "uv",
            "args": [
                "--directory",
                "D:\\code\\search-server",
                "run",
                "search"
            ],
            "env": []
        }
    }
}

3. Restart Claude Desktop for the changes to take effect