mcp-blackbots

MCP server (Model Context Protocol) que expõe dados de mercado da B3 + OKX e o histórico de ideias do CNPI BlackBots como ferramentas pro Claude.

Funciona em qualquer lugar (Claude Code, Claude Desktop, Cursor, etc.) — só precisa de conta BlackBots ativa.

Install

claude mcp add -s user mcp-blackbots -- npx -y mcp-blackbots

(Ou registra manualmente no ~/.claude.json.)

Como usar

Após registrar, peça qualquer coisa no Claude:

> qual o setup atual do PETR4?

Na primeira tool chamada, o Claude vai mostrar uma mensagem do tipo:

Pra usar essa ferramenta, autorize o mcp-blackbots na sua conta BlackBots. Abre https://blackbots.com.br/mcp/auth?code=ABCD-1234

Abre o link, faz login na BlackBots (se ainda não está), clica em "Autorizar" e refaz a pergunta no chat. A partir daí, o token fica salvo em ~/.mcp-blackbots/auth.json e nunca mais é pedido (até você revogar).

Tools

| Tool | Descrição | |---|---| | get_recent_candles | Últimos N candles OHLCV de um ativo | | get_indicators | RSI, ATR, EMA, Bollinger, ADX, VWAP, S/R, vol médio | | get_order_book | Top-N bids/asks (snapshot atual) | | get_funding_open_interest | Funding rate + OI da OKX | | get_aggressor_flow | Compra/venda agressora últimos N min | | get_correlated_assets | Ativos correlacionados (SPY/QQQ/DXY/Gold/Oil; sector peers) | | get_macro_calendar | Calendário macro (Kalshi US + BR Copom/IPCA) | | get_recent_outcomes | Histórico de ideias do CNPI + hit rate | | get_active_thesis | Tese ativa do CNPI pra um ativo |

Requisitos

• Conta BlackBots em https://blackbots.com.br
• Plano pago ativo (BASIC ou MASTER) — feature mcp_access

Configuração avançada

| Env var | Default | Descrição | |---|---|---| | MCP_BLACKBOTS_API_BASE_URL | https://api.blackbots.com.br | Endpoint da API (override pra dev) | | MCP_BLACKBOTS_STATE_DIR | ~/.mcp-blackbots | Onde salva o token + estado OAuth | | MCP_LOG_FILE | (stderr) | Caminho de log opcional | | LOG_LEVEL | info | Nível de log pino |

Revogar acesso

No site da BlackBots → Configurações → Tokens MCP → "Revogar". Próxima tool call vai falhar e o fluxo de autorização recomeça.

Build a partir do source

npm install
npm run build
npm link

Versão

v2.0.0 — totalmente HTTP, sem Redis direto, com OAuth device flow.