# mcp-mercado-financeiro-brasil

> 🚧 **Em construção (Fase 1).** Projeto em desenvolvimento ativo — a API das tools e o
> catálogo de fontes ainda podem mudar. Use com cautela e acompanhe o roadmap abaixo.

Servidor **MCP (Model Context Protocol)** que conecta assistentes de IA (Claude Desktop,
Claude Code, Cursor, Windsurf) a dados do **mercado financeiro brasileiro** via fontes
públicas. Núcleo **zero-cadastro**, `async`, com cache e degradação graciosa.

> **AVISO:** conteúdo informativo/educativo. **Não** constitui recomendação de
> investimento. Rentabilidade passada não garante resultados futuros.

## Ferramentas (Fase 1)

| Módulo | Tools |
|---|---|
| **indicadores** | `get_selic`, `get_cdi`, `get_ipca`, `get_igpm`, `get_poupanca`, `get_serie_sgs`, `rentabilidade_real` |
| **cambio** | `get_cotacao` (PTAX), `historico_cambio` |
| **renda_fixa** | `listar_titulos_tesouro`, `get_titulo_tesouro`, `simular_tesouro` |
| **calculadoras** | `juros_compostos`, `converter_taxa`, `rentabilidade_vs_cdi`, `imposto_renda_renda_fixa` |
| **meta** | `health_check`, `fontes_de_dados` |

Fontes: **BACEN SGS**, **BACEN PTAX (Olinda)**, **Tesouro Transparente** — todas sem chave.
Ações/FIIs (brapi.dev) e cripto (CoinGecko) chegam nas fases 2/3 como **opcionais** via token.

## Instalação

```bash
# execução efêmera (recomendado)
uvx mcp-mercado-financeiro-brasil

# ou permanente
pip install mcp-mercado-financeiro-brasil
```

### Claude Desktop / Cursor

```json
{
  "mcpServers": {
    "mercado-financeiro-brasil": {
      "command": "uvx",
      "args": ["mcp-mercado-financeiro-brasil"]
    }
  }
}
```

## Desenvolvimento

```bash
uv sync --extra dev
uv run pytest          # testes unitários (mockados)
uv run pytest -m integration  # testes que batem nas APIs reais
uv run ruff check .
uv run mypy src
```

## Variáveis de ambiente (opcionais)

| Variável | Padrão | Uso |
|---|---|---|
| `MCP_MFB_LOG_LEVEL` | `INFO` | Nível de log |
| `MCP_MFB_HTTP_TIMEOUT` | `20` | Timeout HTTP (s) |
| `MCP_MFB_CACHE_TTL` | `300` | TTL do cache (s) |
| `MCP_MFB_BRAPI_TOKEN` | — | Ativa ações/FIIs (fase 2) |
| `MCP_MFB_COINGECKO_KEY` | — | Ativa cripto (fase 2) |

## Licença

MIT