copom-mcp

Servidor MCP (Model Context Protocol) que dá a assistentes de IA, como Claude Desktop, Claude Code, Cursor e VS Code, acesso às 261 atas do Copom (de 1998 até hoje) e aos indicadores oficiais do Banco Central do Brasil. Pergunte em português e receba respostas com citação do parágrafo e da reunião de onde veio cada afirmação.

"Como o Copom passou a falar das tarifas americanas em 2025?" "Compare o tom das duas últimas reuniões." "Em quais reuniões houve voto divergente e o que a minoria defendia?"

Não precisa de chave de API: o servidor só entrega os dados, e quem responde é o assistente que você já usa.

O que tem aqui

Related MCP server: losbeto

Instalação

Precisa do uv (pip install uv) ou de Python 3.11+.

Claude Code

claude mcp add copom -- uvx --from git+https://github.com/FelipeYabiko/copom-mcp copom-mcp

Claude Desktop: em Configurações → Desenvolvedor → Editar configuração, adicione:

{
  "mcpServers": {
    "copom": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/FelipeYabiko/copom-mcp", "copom-mcp"]
    }
  }
}

Busca semântica (opcional). A instalação padrão usa só palavras-chave e é leve. Para a busca híbrida, use copom-mcp[semantic] no lugar de copom-mcp. Na primeira vez, o servidor baixa um modelo de ~220 MB e gera os embeddings, o que leva alguns minutos, em segundo plano: ele responde ao cliente na hora e busca só por palavras-chave até o índice ficar pronto (o campo modo_de_busca mostra o estado).

Ferramentas

Também há recursos (copom://reunioes, copom://atas/{reuniao}) e prompts (analisar_reuniao, comparar_reunioes).

Saída real de listar_reunioes(desde="2026"):

276ª  2026-01-28  15.00% → 15.00%  manutenção (+0 pb)
277ª  2026-03-18  15.00% → 14.75%  corte (-25 pb)
278ª  2026-04-29  14.75% → 14.50%  corte (-25 pb)
279ª  2026-06-17  14.50% → 14.25%  corte (-25 pb)
280ª  2026-08-05  14.25% → 14.00%  corte (-25 pb)
281ª  2026-09-16  14.00% → 13.75%  corte (-25 pb)

E de buscar_atas("choque de tarifas comércio internacional", desde="2025"):

271ª (2025-06-18) B) Cenários e análise de riscos §6: O cenário externo mostra-se adverso e particularmente
incerto. O Comitê avaliou que houve alguns desenvolvimentos que permitiriam a conclusão de uma melhora no
cenário internacional, como a reversão parcial das tarifas, mas...

270ª (2025-05-07) B) Cenários e análise de riscos §7: O cenário externo mostra-se adverso e particularmente
incerto. O choque de tarifas e o choque de incerteza, apesar de todas as tentativas de mensuração...

Avaliação

Busca

25 perguntas, cada uma com um gabarito em forma de expressão regular sobre o texto das atas. "Diretas" usam a palavra que está no texto; "paráfrases" descrevem o tema com outras palavras (por exemplo, "guerra comercial" quando a ata diz "choque de tarifas").

O que os números mostram:

• Os embeddings pequenos quase não ajudam nas paráfrases. O MiniLM lê só 128 tokens, e os parágrafos têm até 450. O EmbeddingGemma, maior e mais recente, põe o resultado certo mais no topo (melhor MRR) e acerta todas as diretas, mas erra mais paráfrases, pesa 1,2 GB e levou 49 minutos para indexar o corpus na CPU. Nenhum modelo ganhou com folga, então o padrão é o MiniLM: o melhor hit@5 com 220 MB.

• Num servidor MCP, quem escreve a busca é o modelo. Por isso a descrição de buscar_atas ensina o vocabulário do Copom e sugere várias buscas curtas. Na prática, isso resolve boa parte das paráfrases sem nenhum modelo extra.

• O CI roda o eval do BM25 e falha se a qualidade cair abaixo da linha de base.

Para reproduzir: python evals/run_busca.py (adicione --semantica --modelo <nome> para os outros).

Extração

copom-mcp extrair (com ANTHROPIC_API_KEY) analisa cada ata com o Claude e python evals/run_extracao.py compara a decisão, a nova Selic e a variação com a série oficial do BCB, além de somar custo, uso de cache e latência. A ata usada como exemplo no prompt fica fora da conta, para não inflar o resultado.

Com --lote, o id do lote fica em evals/results/lote-pendente.json assim que ele é criado. Se o programa parar durante a espera (até 24 h), o lote segue na Anthropic: rodar de novo com --lote retoma o mesmo lote em vez de criar e pagar outro, e o modo sem --lote se recusa a rodar enquanto houver um pendente.

Testar sem custo. A mesma extração roda em provedores com plano gratuito, pela API compatível com a da OpenAI: mesmo schema e mesmas instruções, com a resposta validada pelo Pydantic e uma nova tentativa quando vem fora do schema. Sem prompt caching nem Batch API, que são da Anthropic.

export GROQ_API_KEY=...                                   # ou GEMINI_API_KEY / OPENROUTER_API_KEY
copom-mcp extrair --provedor groq --limite 5              # as 5 atas mais recentes que faltam
python evals/run_extracao.py --analises evals/results/analises-groq.json

As análises vão para evals/results/analises-<provedor>.json (fora do Git), a não ser que --saida indique outro arquivo. O 429 por minuto é respeitado (retry-after); cota do dia esgotada, chave inválida ou três atas seguidas com erro param a execução, que continua de onde parou na próxima vez.

As análises do pacote (src/copom_mcp/data/analises.json, lidas por analise_reuniao) foram geradas assim, com o Gemini, para as 248 reuniões com decisão: copom-mcp extrair --provedor gemini --saida src/copom_mcp/data/analises.json. No eval, a decisão e a nova Selic batem com a série oficial em todas as 247 avaliadas, e todas as citações (§N) existem na ata. A variação em pontos-base acerta 96,8%: em 8 atas (2005-2006 e 2013), o modelo escreve ±25 pb onde o passo foi maior.

Desenvolvimento

git clone https://github.com/FelipeYabiko/copom-mcp.git && cd copom-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -q                                   # 25 testes, sem internet
copom-mcp buscar "inflação de serviços"     # testar a busca no terminal
npx @modelcontextprotocol/inspector .venv/bin/copom-mcp   # testar o servidor numa interface web

Abrindo o repositório no Claude Code, ele já vem configurado:

• Hooks: ruff depois de cada edição e testes antes de encerrar uma tarefa.

• Skills: /nova-serie, /avaliar-busca e /atualizar-corpus.

• Subagente: revisor, que revisa com o checklist do projeto.

• Servidor MCP: o próprio servidor, via .mcp.json.

Comentar @claude numa issue ou PR aciona a Claude Code GitHub Action, depois de instalar o app e configurar o segredo ANTHROPIC_API_KEY.

Quer entender cada conceito em detalhe? Veja o guia de estudo.

Fonte dos dados

Atas e séries: Banco Central do Brasil, dados públicos. Este projeto não tem vínculo com o Banco Central. Atas anteriores a ~2008 não numeram os parágrafos; nelas, o número do parágrafo é a ordem no texto.

Licença

MIT