Testando o Servidor MCP Brave (com a API de Busca Brave), Aqui Estão Minhas Reflexões:

Você gostaria de potencializar as habilidades do seu assistente de IA com pesquisas na web em tempo real? Imagine seu modelo de linguagem favorito (LLM), como Claude ou GPT-4o, navegando pela internet para buscar as últimas notícias ou encontrar um café aconchegante nas proximidades—tudo isso alimentado pela API do Brave Search e um servidor MCP personalizado. O Protocolo de Contexto do Modelo (MCP) é como uma porta USB para IA, permitindo que ela se conecte a ferramentas como a API do Brave Search para recuperação épica de dados. Neste guia para iniciantes, vou te levar passo a passo sobre como construir um servidor MCP que se conecta à API do Brave Search, com uma vibe conversacional tão relaxante quanto uma tarde ensolarada. Nenhum doutorado é necessário—apenas um pouco de curiosidade e um teclado. Pronto para transformar sua IA em um mago das pesquisas? Vamos lá!

O que é um Servidor MCP com a API do Brave Search?

Então, o que é esse servidor MCP? O Protocolo de Contexto do Modelo (MCP) é um padrão aberto da Anthropic que permite que modelos de IA, como Claude, se conectem a ferramentas e fontes de dados externas por meio de uma configuração cliente-servidor. Um servidor MCP é como um intermediário que expõe ferramentas—pense em pesquisa na web, acesso a arquivos ou até mesmo integração com o GitHub—para sua IA através de chamadas padronizadas similares a API. A API do Brave Search, por sua vez, é um motor de busca focado em privacidade que fornece resultados de pesquisa na web e locais, com recursos como paginação, controles de frescor e fallbacks inteligentes (por exemplo, mudar para pesquisa na web se os resultados locais estiverem vazios).

Combinando os dois, você cria um servidor MCP que permite que sua IA consulte a API do Brave Search para informações em tempo real—como encontrar a melhor pizza da cidade ou as últimas notícias de tecnologia—sem sair do seu ambiente aconchegante de IA. Por que isso é legal? É privado, rápido e dá superpoderes à sua IA. Vamos construir um!

Configurando Seu Ambiente para o Servidor MCP do Brave Search: Os Fundamentos

Antes de codificarmos nosso servidor MCP, vamos preparar seu sistema. A configuração é simples, mas vamos com calma para manter tudo amigável para iniciantes.

Passo 1: Requisitos

Você vai precisar de:

• Python: Versão 3.9+ para rodar o servidor. Verifique com python --version. Sem Python? Baixe em python.org.
• Node.js: Para rodar o servidor MCP do Brave Search via npx. Verifique com node --version. Pegue em nodejs.org.
• Chave da API do Brave Search: Inscreva-se em brave.com/search/api, escolha um plano (o nível gratuito oferece 2.000 consultas/mês) e gere sua chave a partir do painel.
• Editor de Texto: VS Code ou qualquer editor para ajustar as configurações.
• Terminal: Terminal (Mac/Linux) ou PowerShell (Windows).

Passo 2: Criar uma Pasta de Projeto

Vamos manter as coisas organizadas:

mkdir brave-mcp-server
cd brave-mcp-server

Passo 3: Configurar um Ambiente Virtual

Para evitar confusão com pacotes, crie um ambiente virtual Python:

python -m venv venv

Ative-o:

• Mac/Linux: source venv/bin/activate
• Windows: venv\Scripts\activate

Você verá (venv) no seu terminal—legal!

Obtendo a Chave da API do Brave Search

A API do Brave Search precisa de uma chave API para funcionar. Aqui está como conseguir uma:

1. Visite brave.com/search/api e inscreva-se.
2. Escolha o nível gratuito (2.000 consultas/mês) ou um plano pago se você for grande.
3. No painel do desenvolvedor, clique em “Gerar Chave API.” Copie-a e salve em um lugar seguro (não em um repositório público!).

Vamos armazenar essa chave com segurança em um momento. Por enquanto, vamos instalar as ferramentas do servidor MCP.

Instalando o Servidor MCP do Brave Search

O servidor MCP do Brave Search está disponível via npm, tornando a configuração um passeio no parque com Node.js. Vamos instalá-lo:

Passo 1: Instalar Dependências

Com seu ambiente virtual ativo, instale pacotes Python para interações do cliente MCP:

pip install requests aiohttp asyncio python-dotenv

Esses pacotes lidam com requisições HTTP e variáveis de ambiente. O Node.js cuida do próprio servidor, então certifique-se de que está instalado.

Passo 2: Testar o Pacote MCP do Brave Search

Execute o pacote do servidor para confirmar que está acessível:

npx -y @modelcontextprotocol/server-brave-search

Se ocorrer um erro (por exemplo, “BRAVE_API_KEY not set”), não se preocupe—vamos configurar isso a seguir. Se ele rodar e aguardar, você está no caminho certo. No Windows, você pode encontrar um erro ENOENT se npx não for encontrado—tente usar o caminho completo do Node.js (mais sobre isso mais tarde).

Configurando o Servidor MCP do Brave Search

Certo, vamos preparar seu servidor MCP para se conectar à API do Brave Search! Para isso, você precisará abrir o arquivo de configuração do servidor MCP para seu IDE ou cliente MCP de sua escolha—como claude_desktop_config.json para Claude Desktop, .cursor/mcp.json para Cursor, .codium/windsurf/mcp_config.json para Codium/Windsurf, ou settings.json para VS Code—and adicionar algumas configurações específicas. Também vamos armazenar sua chave da API do Brave Search de forma segura para manter as coisas protegidas. Vamos fazer isso passo a passo!

Passo 1: Criar um Arquivo .env

Para manter sua chave da API do Brave Search segura, vamos usar um arquivo .env:

touch .env

Abra-o no seu editor favorito e adicione:

BRAVE_API_KEY=sua-chave-api-aqui

Substitua sua-chave-api-aqui pela sua verdadeira chave da API do Brave Search do painel do Brave. Salve o arquivo e adicione .env ao seu .gitignore para mantê-lo privado—ninguém precisa ver seus segredos! Assim, seu servidor MCP pode pegar a chave sem codificá-la diretamente.

Passo 2: Atualizar o Arquivo de Configuração do IDE

Agora, abra o arquivo de configuração do servidor MCP para seu IDE ou cliente. Dependendo do que você está usando, isso pode ser:

• Claude Desktop: claude_desktop_config.json (Mac: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %UserProfile%\AppData\Roaming\Claude\claude_desktop_config.json)
• Cursor: .cursor/mcp.json (normalmente no seu diretório de projeto ou no diretório inicial)
• Codium/Windsurf: .codium/windsurf/mcp_config.json (verifique em ~/.codium/windsurf/)
• VS Code: settings.json (encontre via Code > Preferences > Settings > Extensions > MCP ou ~/.vscode/settings.json)

Se o arquivo não existir, crie-o na localização apropriada (por exemplo, use touch claude_desktop_config.json para Claude). Abra-o no seu editor e adicione a seguinte configuração para informar ao seu servidor MCP como executar o serviço do Brave Search.

Para Mac/Linux:

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "$BRAVE_API_KEY"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Para Windows:

{
  "mcpServers": {
    "brave-search": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\Users\\SeuNomeDeUsuário\\AppData\\Roaming\\npm\\node_modules\\@modelcontextprotocol\\server-brave-search\\dist\\index.js"],
      "env": {
        "BRAVE_API_KEY": "$BRAVE_API_KEY"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Algumas notas:

• Chave API: A linha "BRAVE_API_KEY": "$BRAVE_API_KEY" puxa sua chave do arquivo .env usando python-dotenv (mais sobre isso no script do cliente depois). Se preferir, substitua $BRAVE_API_KEY pela sua chave real (por exemplo, "sk-xxx"), mas o método .env é mais seguro.
• Caminho do Windows: Para Windows, substitua SeuNomeDeUsuário pelo seu nome de usuário real. Para encontrar o caminho exato do Node.js, execute Get-Command node | Select-Object Source no PowerShell ou where node no Prompt de Comando. Para o caminho de args, localize o módulo @modelcontextprotocol/server-brave-search nos seus módulos globais npm (normalmente C:\Users\SeuNomeDeUsuário\AppData\Roaming\npm\node_modules). Se você encontrar um erro ENOENT, verifique esses caminhos.
• Mesclando Configurações: Se seu arquivo de configuração já tiver um objeto mcpServers, adicione a entrada "brave-search" a ele, assim:

{
  "mcpServers": {
    "servidor-existente": { ... },
    "brave-search": { ... }
  }
}

Passo 3: Salvar e Verificar

Salve o arquivo de configuração no local correto para seu IDE ou cliente:

• Claude Desktop: Mac: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %UserProfile%\AppData\Roaming\Claude\claude_desktop_config.json
• Cursor: Coloque .cursor/mcp.json na raiz do seu projeto ou no diretório inicial (~/.cursor/).
• Codium/Windsurf: Salve .codium/windsurf/mcp_config.json em ~/.codium/windsurf/.
• VS Code: Atualize settings.json em ~/.vscode/ ou via a interface de configurações do VS Code.

Se a pasta não existir, crie-a (por exemplo, mkdir -p ~/Library/Application Support/Claude no Mac). Esta configuração informa ao seu cliente MCP (como Claude ou Cursor) como lançar o servidor MCP para a API do Brave Search. Para testar, reinicie seu IDE ou cliente para carregar as novas configurações—vamos verificar se funciona quando executarmos o script do cliente mais tarde!

Construindo um Cliente MCP Simples para Testar o Servidor MCP do Brave Search

Vamos criar um script Python para testar seu servidor MCP com a API do Brave Search. Esse cliente mimetizará como o Claude Desktop interage com o servidor.

Passo 1: Criar o Script do Cliente

Crie brave_mcp_client.py:

import asyncio
import os
from dotenv import load_dotenv
from fastmcp.client import MCPClient

async def main():
    # Carregar variáveis de ambiente
    load_dotenv()

    # Criar MCPClient a partir do arquivo de configuração
    client = MCPClient.from_config_file("claude_desktop_config.json")

    # Fazer uma consulta de pesquisa
    response = await client.request(
        {"method": "brave_web_search"},
        {"query": "melhores cafeterias em Seattle", "count": 10}
    )
    print(f"Resultados da Pesquisa: {response}")

if __name__ == "__main__":
    asyncio.run(main())

Esse script:

• Carrega sua chave da API do Brave Search do arquivo .env.
• Usa fastmcp para se conectar ao servidor MCP.
• Envia uma consulta de pesquisa pela web via a ferramenta brave_web_search.

Passo 2: Instalar fastmcp

Instale a biblioteca cliente MCP:

pip install fastmcp

Passo 3: Executar o Cliente

Com seu ambiente virtual ativo:

python brave_mcp_client.py

Se tudo correr bem, o servidor MCP inicia, consulta a API do Brave Search, e imprime resultados como uma lista JSON de cafeterias. Eu consegui uma lista deliciosa de cafés em Seattle em segundos! Se você vê erros, verifique:

• Chave API: Verifique se é válida em .env ou na configuração.
• Registros: No Claude Desktop, vá para Configurações > Desenvolvedor para visualizar os registros em %UserProfile%\AppData\Roaming\Claude\Logs\ (Windows) ou ~/Library/Application Support/Claude/Logs/ (Mac).
• Caminho do Node.js: Usuários do Windows, verifique o caminho do command na configuração.

Integrando a API do Brave Search com o Claude Desktop

Para usar seu servidor MCP com o Claude Desktop:

1. Instalar Claude Desktop: Baixe do site oficial da Anthropic e instale.
2. Adicionar a Configuração: Certifique-se de que claude_desktop_config.json está na pasta correta (veja acima).
3. Reiniciar Claude: Feche completamente (Command+Q no Mac) e reabra.
4. Testar uma Consulta: No chat do Claude, digite: “Pesquise na web as melhores cafeterias em Seattle.” Claude solicitará permissão para usar o servidor MCP, e então mostrará os resultados.

Você deve ver o Claude registrar “Fazendo uma solicitação de ferramenta: brave_web_search” e buscar resultados via a API do Brave Search. Meu teste retornou ótimos locais de café sem nenhuma dificuldade!

Para outros IDEs impulsionados por IA como Codium/Windsurf, VS Code e Cursor. Ao reutilizar a mesma configuração da API do Brave Search, você pode habilitar essas ferramentas para realizar buscas na web através do servidor MCP, permitindo que assistentes de IA busquem dados em tempo real diretamente na interface de chat de cada IDE. O processo é semelhante e envolve colar a configuração existente nas definições do MCP apropriadas para cada IDE, com ajustes menores para usuários do Windows para garantir caminhos corretos do Node.js, como mencionado anteriormente.

E para guias mais detalhados sobre como configurar servidores MCP em diferentes ambientes, visite apidog.com/blog, onde você encontrará recursos úteis para integrar a API do Brave Search (e muitos outros servidores mcp) com suas ferramentas de codificação preferidas.

Por que usar a API do Brave Search com um Servidor MCP?

Essa combinação é incrível porque:

• Dados em Tempo Real: A API do Brave Search captura resultados frescos da web e locais, ao contrário do conhecimento estático de LLM.
• Foco em Privacidade: A abordagem priorizando a privacidade da Brave mantém as pesquisas seguras.
• Integração Fácil: A configuração do servidor MCP é plug-and-play com ferramentas como Claude.

Comparado ao servidor MCP do Perplexity, a API da Brave oferece pesquisa local e filtragem flexível, tornando-a uma escolha top.

Dicas Profissionais para o Sucesso do MCP do Brave Search

• Valide a Configuração: Use um validador JSON para capturar erros de digitação em claude_desktop_config.json.
• Verifique os Registros: Depure nas configurações de desenvolvedor do Claude se o servidor falhar.
• Experimente a Pesquisa Local: Consulte “restaurantes perto de mim” para testar o fallback local da API do Brave Search.
• Explore Mais Servidores: Confira mcp.so para servidores como Firecrawl (raspagem da web) ou GitHub.

Concluindo: Sua Aventura com o MCP do Brave Search Começa

Parabéns—você construiu um servidor MCP que aproveita a API do Brave Search para tornar sua IA uma estrela das pesquisas! Desde configurar o Node.js até consultar cafeterias com Claude, você está pronto para explorar a web com IA. Tente buscar notícias, serviços locais ou até mesmo tópicos de nicho a seguir. A lista de servidores MCP tem mais ferramentas para brincar, e a comunidade MCP do Claude em claudemcp.com está repleta de ideias. Então, qual será sua próxima consulta? Últimas tendências tecnológicas? Um restaurante escondido? E não esqueça de visitar apidog.com para aquele polimento extra na API.