mcp-bcb

Servidor MCP que dá a assistentes de IA (Claude, Cursor, VS Code...) acesso a dados econômicos oficiais do Banco Central do Brasil: Selic, CDI, IPCA, IGP-M, INCC, câmbio e as projeções do Boletim Focus.

Em vez de chutar um número, o assistente consulta a fonte oficial:

Você: Quanto R$ 1.000 de janeiro de 2020 valem hoje, corrigidos pelo IPCA?

Claude: (chama corrigir_valor) R$ 1.446,51, uma inflação acumulada de 44,65% entre jan/2020 e set/2026. O IPCA de outubro ainda não foi divulgado.

Ferramentas

Ferramenta	O que faz
buscar_serie	Valores de qualquer série do SGS (por apelido como ipca, selic, dolar ou por código), com resumo e variação acumulada
expectativas_focus	Mediana, média, mínimo e máximo das projeções do mercado para IPCA, Selic, câmbio, PIB e IGP-M
corrigir_valor	Corrige um valor pela inflação ou calcula o rendimento por um percentual do CDI ou da Selic
listar_series	Séries com atalho por nome

Como usar

Opção 1: local, via npx

No Claude Desktop, adicione em claude_desktop_config.json:

{
  "mcpServers": {
    "bcb": { "command": "npx", "args": ["-y", "mcp-bcb"] }
  }
}

No Claude Code:

claude mcp add bcb -- npx -y mcp-bcb

Opção 2: remoto, sem instalar nada

No claude.ai, vá em Configurações → Conectores → Adicionar conector personalizado e cole:

https://mcp-bcb.SEU_USUARIO.workers.dev/mcp

Arquitetura

Monorepo em TypeScript com arquitetura hexagonal enxuta: a lógica fica no core e as duas entradas só montam as dependências.

packages/
├── core/      domínio (cálculos, datas, catálogo), portas, adaptadores do BCB e ferramentas MCP
├── cli/       entrada stdio → publicada no npm como `mcp-bcb`
└── worker/    entrada HTTP → Cloudflare Workers, com cache opcional no KV

• Domínio puro: os cálculos usam decimal.js, sem float, e não sabem nada de MCP ou HTTP.
• Cache como decorador: SeriesComCache e FocusComCache embrulham os clientes do BCB; séries diárias ficam 3 h em cache e mensais, 12 h.
• Erros úteis para o modelo: entradas inválidas e falhas da API viram mensagens que o assistente entende e corrige sozinho.
• Robustez: os clientes repetem a chamada uma vez em timeout ou erro 5xx, quebram consultas diárias longas em janelas de 9 anos (o SGS aceita no máximo 10) e descartam as datas futuras que a série da meta Selic traz.

Desenvolvimento

Requer Node 20+ e pnpm.

pnpm install
pnpm test          # testes unitários e das ferramentas, com fontes falsas
pnpm typecheck
pnpm smoke         # compila a CLI e chama as ferramentas contra as APIs reais
pnpm inspector     # abre o MCP Inspector para testar na mão
pnpm dev:worker    # Worker local em http://localhost:8787/mcp

Publicação

npm:

pnpm --filter mcp-bcb publish --access public

Cloudflare Workers: é grátis até 100 mil requisições por dia.

pnpm deploy:worker

Para compartilhar o cache entre instâncias, crie um namespace KV com npx wrangler kv namespace create CACHE e descomente o bloco kv_namespaces em packages/worker/wrangler.jsonc.

Fontes dos dados

• SGS - Sistema Gerenciador de Séries Temporais (api.bcb.gov.br)
• Expectativas de Mercado - Focus (API Olinda)

Projeto independente, sem vínculo com o Banco Central do Brasil.

Licença

MIT