Search MCP Server

Um servidor de busca versátil que suporta múltiplos mecanismos de busca, incluindo Brave, Metaso e Bocha.

Documentação

Search MCP Server

Uma implementação de serviço de busca baseada no protocolo MCP, com suporte a múltiplos mecanismos de busca, que pode ser integrada perfeitamente ao Cursor e ao Claude Desktop.

Desenvolvido em Python, com suporte a processamento assíncrono e alta concorrência de requisições. Atualmente, oferece suporte a três mecanismos de busca:

Brave Search: uma empresa estrangeira especializada em serviços de interface de busca
Metaso Search: implementação reversa da interface do Metaso AI Search, não é uma interface oficial
Bocha Search: o produto de API de busca com maior participação de mercado no país

Para mais conhecimento sobre MCP, consulte o AI Book ( 一文看懂什么是MCP(大模型上下文)？用来干什么的？怎么用它？)

Autor: Ling Feng (WeChat: fengin)

Site: https://aibook.ren (AI Book)

Exemplo de uso

Características

Suporte a múltiplos mecanismos de busca:
- Brave Search: oferece busca na web e busca por localização
- Metaso Search: oferece busca na web e busca acadêmica, com suporte aos modos conciso e aprofundado
- Bocha Search: oferece busca na web, com suporte a filtro por intervalo de tempo, resumo detalhado e busca de imagens
Cenários de uso: integração perfeita com Claude Desktop ou Cursor, ampliando muito a capacidade de obtenção de conteúdo das ferramentas
Design modular: cada mecanismo de busca é um módulo independente, podendo ser copiado separadamente para uso em outros lugares

Escolha entre os três mecanismos de busca

Apenas um mecanismo de busca pode estar ativo por vez durante a execução. Para facilitar a escolha de qual configurar, listei uma comparação aproximada:

Mecanismo de busca	Nacional/Internacional	Requer VPN	Resumo automático	Qualidade	Gratuito	Oficial	Velocidade	Dificuldade de registro
Brave	Internacional	Sim	Não	Alta	Sim (limitado)	Sim	Média	Muito alta
Metaso	Nacional	Não	Sim	Média	Sim	Não	Lenta (resumo por IA)	Baixa
Bocha	Nacional	Não	Não	Alta	Não	Sim	Muito rápida	Baixa

Instalação e uso

1. Requisitos de ambiente

Python 3.10+
uv 0.24.0+
node.js v20.15.0
cursor >=0.45.10 (em versões abaixo, a configuração do servidor MCP frequentemente não conecta)
Acesso à internet sem restrições (necessário apenas para usar o Brave Search)

1.1 Instalação do driver do navegador (necessário apenas para Metaso)

# 安装Playwright框架
pip install playwright>=1.35.0
# 安装浏览器驱动,仅安装chromium
playwright install chromium

2. Baixar o código

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

3. Ativar o mecanismo de busca desejado

Abra o diretório raiz do projeto e modifique o código em server.py para selecionar o tipo de ativação:

# 搜索引擎配置
SEARCH_ENGINE = os.getenv("SEARCH_ENGINE", "bocha")

Os valores correspondem a brave, metaso e bocha. Também é possível configurar por meio da variável de ambiente SEARCH_ENGIN

4. Configurar o módulo de busca correspondente

Cada um dos três diretórios de módulos abaixo possui um arquivo config.py:

src\search\proxy\brave
src\search\proxy\metaso
src\search\proxy\bocha

De acordo com sua escolha, modifique o arquivo config.py correspondente

4.1 Configuração do Brave Search

# 检查API密钥
BRAVE_API_KEY = os.getenv("BRAVE_API_KEY")
if not BRAVE_API_KEY:
    BRAVE_API_KEY = "你申请的 brave_api_key"

Se for usar no Claude Desktop, também é possível configurar esse parâmetro por meio de variáveis de ambiente nas configurações do Claude Desktop. No entanto, o Cursor atualmente não suporta variáveis de ambiente, então a modificação deve ser feita neste arquivo.

Endereço para solicitação da API KEY: Brave Search - API

O requisito de registro é relativamente alto, exigindo:

VPN (também necessária durante o uso)
Verificação de e-mail
Cartão de crédito (pode ser virtual: https://cardgenerator.org/)

4.2 Configuração do Metaso

# 认证信息
METASO_UID = os.getenv("METASO_UID")
METASO_SID = os.getenv("METASO_SID")
if not METASO_UID or not METASO_SID:
    METASO_UID = "你获取的 metaso_uid"
    METASO_SID = "你获取的 metaso_sid"

Da mesma forma, no Claude Desktop, é possível configurar por meio de variáveis de ambiente nas configurações de MCP Servers;

Como obter uid e sid:

Entre no Metaso AI Search, faça login na conta (recomenda-se fazer login na conta, caso contrário, podem ocorrer limitações estranhas), pressione F12 para abrir as ferramentas de desenvolvedor e encontre os valores de uid e sid em Application > Cookies.

Integração com múltiplas contas

Nota: atualmente suspeita-se que o Metaso tenha limites no número total de buscas por endereço IP, recomenda-se adicionar rotação de IP

Você pode fornecer múltiplos pares de uid-sid e usar , para modificar o código de uso correspondente. A cada requisição, o serviço selecionará um deles. Considerarei isso posteriormente.

4.3 Configuração do Bocha

BOCHA_API_KEY = os.getenv("BOCHA_API_KEY", "")
if not BOCHA_API_KEY:
    BOCHA_API_KEY="你申请的 bocha_api_key"

Endereço para registro e solicitação: https://open.bochaai.com/

A cobrança é por chamada e não é barata, mas a qualidade da busca é realmente boa. Tenho alguns códigos de teste gratuitos em quantidade limitada. Se precisar, entre em contato comigo pelo WeChat.

5. Configuração das ferramentas de IA

5.1 Configuração no Cursor

name: search
type: cmd
command: uv --directory D:\code\search-server run search

Onde "D:\code\search-server" é o diretório do código-fonte que você baixou

5.2 Configuração no Claude Desktop

Encontre o arquivo de configuração

Método 1

# widnows
C:\Users\{用户}\AppData\Roaming\Claude\claude_desktop_config.json
# mac/linux 应该在用户家目录下找

Método 2

Abra o aplicativo Claude Desktop e navegue até: Claude Desktop—>Menu—>Settings—>Developer—>Edit Config

Edite e adicione o seguinte MCP Server:

{
  "mcpServers": {
    "search": {
            "command": "uv",
            "args": [
                "--directory",
                "D:\\code\\search-server",
                "run",
                "search"
            ],
            "env": {
                "BRAVE_API_KEY": "你申请的API KEY"
            }
        }
  }
}

As variáveis de ambiente dependem da sua necessidade. Se o código já foi modificado, não é necessário configurá-las.

O Cursor abrirá uma janela preta. Não a feche, não a feche. Esse é o processo do servidor MCP em execução. Atualmente, não há como evitar que ela apareça.

Após configurar o Claude Desktop, é obrigatório reiniciar o aplicativo para que as alterações tenham efeito.

5.4 Solução de problemas

Muitas pessoas encontram problemas após configurar o Cursor: mesmo após configurar em MCP Servers, o status ainda mostra um ponto vermelho, "Tools Not Found", e as ferramentas não são chamadas durante o uso. Isso ocorre porque a configuração não foi feita corretamente.

Os casos mais comuns são:

Ambiente não preparado, incluindo os softwares e versões necessários, conforme detalhado na seção de ambiente
Ambiente preparado incorretamente. Por exemplo, no Windows existem o terminal cmd, o terminal powershell e possivelmente o terminal gitbash. Abra o terminal cmd (geralmente é o que o cursor usa) e verifique o ambiente executando diretamente: uv --directory D:\code\search-server run search
Caminho/comando de configuração incorreto. Abra o terminal e execute o comando para verificar: uv --directory D:\code\search-server run search
A janela preta foi fechada. Para reabri-la, é necessário reiniciar o Cursor
Versão do Cursor muito antiga

Erro em tempo de execução indicando que o chromium não está instalado. A solução está na seção 1.1 de preparação do ambiente

错误:搜索执行错误:BrowserType.launch persistent context:Executable doesn't exist atC:\Users\fengi\AppDatalLocal\ms-playwright\chromium headless shell-1155\chrome-winlheadless shell.exe

6. Uso

No seu Claude Desktop ou Cursor, basta trabalhar normalmente. Quando necessário, ele chamará automaticamente a interface de busca para obter conteúdo. Por exemplo, se você pedir para organizar as tendências de desenvolvimento tecnológico na web para 2025 como conteúdo de software, ele chamará a ferramenta de busca para obter informações da internet:

Após configurar a ferramenta, ele saberá que ela existe em suas informações
De acordo com sua solicitação, ele analisará e decidirá automaticamente se precisa usar a ferramenta de busca
Com base na necessidade, extrairá palavras-chave e chamará a ferramenta de busca
Com base no conteúdo retornado, organizará o resultado que você deseja

Um ponto importante: no Cursor, é necessário ativar o modo agent do composer para que funcione. Ao chamar a ferramenta, também é necessário clicar em executar.

Detalhes técnicos

Estrutura do projeto

search/
├── __init__.py
├── server.py              # MCP服务器实现
└── proxy/                 # 搜索引擎代理
    ├── brave/             # Brave搜索模块
    │   ├── __init__.py
    │   ├── client.py      # 核心客户端实现
    │   ├── config.py      # 配置和速率限制
    │   └── exceptions.py  # 异常定义
    ├── metaso/            # Metaso搜索模块
    │   ├── __init__.py
    │   ├── client.py      # 核心客户端实现
    │   ├── config.py      # 配置和速率限制
    │   └── exceptions.py  # 异常定义
    ├── bocha/             # 博查搜索模块
    │   ├── __init__.py
    │   ├── client.py      # 核心客户端实现
    │   ├── config.py      # 配置和速率限制
    │   └── exceptions.py  # 异常定义
    ├── brave_search.py    # Brave MCP工具实现
    ├── metaso_search.py   # Metaso MCP工具实现
    └── bocha_search.py    # 博查搜索MCP工具实现

Parâmetros da interface

Mecanismo Brave Search

search
- Executa busca na web, com suporte a paginação e filtros
- Parâmetros de entrada:
  - query (string): palavra-chave da busca
  - count (number, opcional): quantidade de resultados por página (máximo 20)
  - offset (number, opcional): deslocamento de paginação (máximo 9)
location_search
- Busca informações relacionadas a localizações geográficas (comércios, restaurantes, etc.)
- Parâmetros de entrada:
  - query (string): palavra-chave da busca por localização
  - count (number, opcional): quantidade de resultados (máximo 20)
- Quando não há resultados relevantes, alterna automaticamente para busca na web

Mecanismo Metaso

search
- Executa busca na web, com suporte a múltiplos modos
- Parâmetros de entrada:
  - query (string): palavra-chave da busca
  - mode (string, opcional): modo de busca
    - concise: modo conciso, respostas curtas e objetivas
    - detail: modo aprofundado, respostas detalhadas e abrangentes (padrão)
    - research: modo pesquisa, respostas com análise aprofundada (atualmente não suportado, a engenharia reversa não foi bem-sucedida)
scholar_search
- Executa busca acadêmica, especializada em encontrar recursos acadêmicos
- Parâmetros de entrada:
  - query (string): palavra-chave da busca acadêmica
  - mode (string, opcional): modo de busca, igual ao acima

Mecanismo Bocha

search
- Executa busca na web, com suporte a filtro por intervalo de tempo e resumo detalhado
- Parâmetros de entrada:
  - query (string): palavra-chave da busca
  - count (number, opcional): quantidade de resultados (1-10, padrão 10)
  - page (number, opcional): número da página, começando em 1
  - freshness (string, opcional): intervalo de tempo
    - noLimit: sem limite de tempo (padrão)
    - oneDay: dentro de um dia
    - oneWeek: dentro de uma semana
    - oneMonth: dentro de um mês
    - oneYear: dentro de um ano
  - summary (boolean, opcional): se deve exibir resumo detalhado, padrão false
- Conteúdo retornado:
  - Estatísticas da busca (total de resultados, página atual/total de páginas, quantidade de resultados na página)
  - Resultados da busca na web (título, URL, fonte, resumo, data de publicação)
  - Informações de imagens relacionadas (dimensões, fonte, URL)