# Servidor MCP para IAs URL: /docs/mcp.mdx Como integrar a Brapi com assistentes de IA usando o Model Context Protocol (MCP) *** title: Servidor MCP para IAs description: Como integrar a Brapi com assistentes de IA usando o Model Context Protocol (MCP) ----- O **Model Context Protocol (MCP)** é um protocolo que permite aos assistentes de IA acessar dados externos em tempo real. O servidor MCP da Brapi fornece integração direta com dados financeiros brasileiros, permitindo que LLMs consultem cotações, históricos e indicadores econômicos atualizados durante conversas. ## O que é o MCP da Brapi O servidor MCP da Brapi é uma implementação do Model Context Protocol que expõe as funcionalidades da API Brapi para assistentes de IA compatíveis. Através dele, você pode: * Consultar cotações de ações da B3 em tempo real * Obter dados históricos e análises fundamentalistas * Acessar preços de criptomoedas e taxas de câmbio * Consultar indicadores econômicos brasileiros ### Funcionamento Quando configurado, o servidor MCP permite que assistentes de IA façam consultas como: ```txt Analise o desempenho da PETR4 no último mês ``` ```txt Compare as principais ações do Ibovespa hoje ``` O assistente automaticamente utiliza as ferramentas MCP para buscar dados atualizados da Brapi e fornecer respostas precisas. ## Instalação ### Requisitos * Node.js >= v18.0.0 * Cliente MCP compatível (Cursor, Claude Desktop, VS Code, Windsurf, etc.) * Token da API Brapi ([obtenha gratuitamente](https://brapi.dev)) ### Cursor Configure o servidor MCP editando o arquivo `~/.cursor/mcp.json` (global) ou `.cursor/mcp.json` (projeto específico). **Configuração:** ```json { "mcpServers": { "brapi": { "command": "npx", "args": [ "mcp-remote", "https://brapi.dev/api/mcp/mcp", "--header", "Authorization:Bearer ${BRAPI_API_KEY}" ], "env": { "BRAPI_API_KEY": "SEU_TOKEN" } } } } ``` ### Claude Desktop Edite o arquivo de configuração `claude_desktop_config.json`: ```json { "mcpServers": { "brapi": { "command": "npx", "args": [ "mcp-remote", "https://brapi.dev/api/mcp/mcp", "--header", "Authorization:Bearer SEU_TOKEN" ] } } } ``` ### VS Code Configure no arquivo de configuração MCP do VS Code: ```json { "mcp": { "servers": { "brapi": { "command": "npx", "args": [ "mcp-remote", "https://brapi.dev/api/mcp/mcp", "--header", "Authorization:Bearer SEU_TOKEN" ] } } } } ``` ### Windsurf Configure no arquivo de configuração MCP do Windsurf: ```json { "mcpServers": { "brapi": { "command": "npx", "args": [ "mcp-remote", "https://brapi.dev/api/mcp/mcp", "--header", "Authorization:Bearer ${BRAPI_API_KEY}" ], "env": { "BRAPI_API_KEY": "SEU_TOKEN" } } } } ``` ### Cline **Configuração:** ```json { "mcpServers": { "brapi": { "command": "npx", "args": [ "mcp-remote", "https://brapi.dev/api/mcp/mcp", "--header", "Authorization:Bearer SEU_TOKEN" ], "disabled": false, "autoApprove": [] } } } ``` ### Zed Configure no arquivo `settings.json` do Zed: ```json { "context_servers": { "Brapi": { "command": { "path": "npx", "args": [ "mcp-remote", "https://brapi.dev/api/mcp/mcp", "--header", "Authorization:Bearer SEU_TOKEN" ] }, "settings": {} } } } ``` **Obtendo sua Chave da API** 1. Acesse [brapi.dev](https://brapi.dev) e crie uma conta 2. No dashboard, gere uma chave da API 3. Substitua `SEU_TOKEN` pela sua chave ## Ferramentas Disponíveis O servidor MCP expõe as seguintes ferramentas para assistentes de IA: ### Ferramentas Públicas (Sem Autenticação) * `get_available_stocks` - Lista ações e índices brasileiros com filtros avançados (setor, tipo, busca, ordenação) * `get_available_currencies` - Lista pares de moedas disponíveis * `get_available_cryptocurrencies` - Lista criptomoedas disponíveis * `get_available_inflation_countries` - Lista países com dados de inflação ### Ferramentas Premium (Chave da API Obrigatória) * `get_stock_quotes` - Cotações e dados históricos de ações * `get_currency_rates` - Taxas de câmbio em tempo real * `get_crypto_prices` - Preços de criptomoedas * `get_inflation_data` - Dados de inflação * `get_prime_rate_data` - Dados da taxa básica de juros ### Autenticação O servidor MCP suporta os mesmos métodos de autenticação da API REST: * **Header Authorization:** `Authorization: Bearer sua_chave_api` (recomendado) * **Header Authorization:** `Authorization: sua_chave_api` * **Query parameter:** `?token=sua_chave_api` ## Dicas de Uso ### Regras Automáticas Configure regras no seu cliente para invocar automaticamente a Brapi em consultas financeiras: **Windsurf (`.windsurfrules`):** ```toml [[calls]] match = "quando o usuário solicita dados financeiros, cotações de ações, preços de criptomoedas ou análise de mercado" tool = "brapi" ``` **Cursor:** Configure em `Settings > Rules` ### Especifique Símbolos Para consultas mais eficientes, mencione os tickers diretamente: ```txt Analise o desempenho da PETR4 nos últimos 3 meses e compare com VALE3 ``` ### Filtros Avançados A ferramenta `get_available_stocks` suporta filtros avançados que permitem consultas mais específicas: **Por Setor:** * `Finance` - Bancos e instituições financeiras * `Energy Minerals` - Petróleo e energia * `Technology Services` - Empresas de tecnologia * `Health Services` - Saúde e medicina * `Retail Trade` - Comércio varejista * `Utilities` - Energia elétrica e saneamento **Por Tipo:** * `stock` - Ações ordinárias e preferenciais * `fund` - Fundos imobiliários (FIIs) * `bdr` - Brazilian Depositary Receipts **Ordenação:** * `volume` - Volume de negociação * `market_cap_basic` - Valor de mercado * `change` - Variação percentual * `close` - Preço de fechamento * `name` - Ordem alfabética ## Exemplos de Consultas Com o MCP configurado, você pode fazer perguntas naturais como: ### Análise de Ações ```txt "Analise o desempenho das ações da Petrobras (PETR4) no último mês e compare com o setor de energia" ``` ```txt "Quais são as 5 ações com melhor performance no Ibovespa hoje?" ``` ```txt "Mostre o histórico de dividendos da Vale (VALE3) nos últimos 2 anos" ``` ### Câmbio e Economia ```txt "Qual é a taxa de câmbio atual USD-BRL e como ela se compara com a média dos últimos 30 dias?" ``` ```txt "Mostre as principais moedas em relação ao Real brasileiro hoje" ``` ### Criptomoedas ```txt "Qual é o preço atual do Bitcoin em Real brasileiro?" ``` ```txt "Compare os preços das principais criptomoedas (BTC, ETH, ADA) em BRL" ``` ### Descoberta de Mercado ```txt "Mostre todas as ações de bancos brasileiros disponíveis" ``` ```txt "Liste as principais empresas de tecnologia listadas na B3" ``` ```txt "Quais são os fundos imobiliários (FIIs) com maior volume de negociação?" ``` ```txt "Mostre as ações do setor de energia ordenadas por valor de mercado" ``` ```txt "Liste todos os BDRs disponíveis ordenados alfabeticamente" ``` O assistente utilizará automaticamente as ferramentas MCP para buscar dados atualizados. ## Solução de Problemas ### Erros de Módulo Não Encontrado Se você encontrar `ERR_MODULE_NOT_FOUND`, tente usar `bunx` em vez de `npx`: ```json { "mcpServers": { "brapi": { "command": "bunx", "args": [ "mcp-remote", "https://brapi.dev/api/mcp/mcp", "--header", "Authorization:Bearer ${BRAPI_API_KEY}" ], "env": { "BRAPI_API_KEY": "SEU_TOKEN" } } } } ``` Isso frequentemente resolve problemas de resolução de módulos em ambientes onde `npx` não instala ou resolve pacotes adequadamente. ### Problemas de Token de API **"Token de autenticação obrigatório" (TOKEN\_REQUIRED)** * Certifique-se de que está fornecendo o cabeçalho Authorization com seu token * Verifique se seu token está copiado corretamente do dashboard * Para ferramentas premium, o token é obrigatório **"Token de API inválido ou expirado" (TOKEN\_INVALID)** * Verifique se seu token não expirou no dashboard da Brapi * Regenere seu token se necessário * Certifique-se de não ter espaços extras no token ### Problemas de TLS/Certificado Use a flag `--experimental-fetch` para contornar problemas relacionados ao TLS: ```json { "mcpServers": { "brapi": { "command": "npx", "args": [ "--node-options=--experimental-fetch", "mcp-remote", "https://brapi.dev/api/mcp/mcp", "--header", "Authorization:Bearer SEU_TOKEN" ] } } } ``` ### Erros Gerais do Cliente MCP 1. Tente adicionar `@latest` ao nome do pacote 2. Use `bunx` como alternativa ao `npx` 3. Considere usar `deno` como outra alternativa 4. Certifique-se de estar usando Node.js v18 ou superior para suporte nativo ao fetch **Exemplo com Deno:** ```json { "mcpServers": { "brapi": { "command": "deno", "args": [ "run", "--allow-env=NO_DEPRECATION,TRACE_DEPRECATION", "--allow-net", "npm:mcp-remote", "https://brapi.dev/api/mcp/mcp", "--header", "Authorization:Bearer SEU_TOKEN" ] } } } ``` ## Segurança O servidor MCP implementa as seguintes práticas de segurança: * **Autenticação obrigatória** para ferramentas premium * **Transmissão segura** via HTTPS/TLS * **Validação de tokens** a cada requisição * **Validação de parâmetros** de entrada * **Controle de acesso** baseado no plano de assinatura ## Limites da API As requisições MCP seguem os mesmos limites da API REST: * **Plano Gratuito:** Até 15.000 requisições por mês * **Plano Startup:** Até 150.000 requisições por mês * **Plano Pro:** Até 500.000 requisições por mês Consulte os [planos disponíveis](https://brapi.dev/pricing) para mais detalhes sobre recursos e funcionalidades de cada plano. ## Clientes Compatíveis O servidor MCP é compatível com qualquer cliente que suporte o protocolo MCP: * **Cursor** - Editor de código com IA * **Claude Desktop** - Aplicativo desktop do Anthropic * **VS Code** - Com extensões MCP * **Windsurf** - IDE com IA integrada * **Cline** - Assistente de desenvolvimento * **Zed** - Editor colaborativo * **Outros clientes MCP** - Qualquer ferramenta compatível ## Próximos Passos 1. [Obtenha sua chave da API](https://brapi.dev) 2. Configure seu cliente MCP seguindo as instruções acima 3. Comece a fazer consultas financeiras em linguagem natural **Recursos Relacionados** * [Documentação da API REST](/docs) * [Exemplos de integração](/docs/examples) * [Suporte](https://brapi.dev/contact) *** **Aviso Legal** Os dados são fornecidos apenas para fins informativos e não constituem aconselhamento financeiro. Consulte sempre um profissional qualificado antes de tomar decisões de investimento.