@databolsa/mcp

🌐 databolsa.com — a plataforma ao vivo · docs da API

Servidor MCP para a API pública e os recursos autenticados da conta no DataBolsa.

Ele expõe operações da API DataBolsa como tools MCP para agentes consultarem dados do mercado brasileiro de forma determinística: ações, FIIs, índices, renda fixa, regime macro, screeners, BDRs, opções, cripto e busca. As tools são geradas no startup a partir do contrato OpenAPI vivo e declaram schemas de entrada e saída. Respostas bem-sucedidas incluem structuredContent validado, além do JSON em texto para compatibilidade com clientes MCP antigos.

Rodando

npx -y @databolsa/mcp

O transporte padrão é stdio, esperado por clientes MCP locais como Claude Desktop e Claude Code.

Claude Desktop

Adicione o servidor ao claude_desktop_config.json:

{
  "mcpServers": {
    "databolsa": {
      "command": "npx",
      "args": ["-y", "@databolsa/mcp"],
      "env": {
        "DATABOLSA_API_URL": "https://api.databolsa.com"
      }
    }
  }
}

Claude Code

API hospedada (requer uma chave de databolsa.com/conta):

claude mcp add databolsa \
  --env DATABOLSA_API_URL=https://api.databolsa.com \
  --env DATABOLSA_API_KEY=db_live_xxx \
  -- npx -y @databolsa/mcp

Alternar entre origens

Use --scope para escolher onde a configuração vive: local (privada, só sua máquina, ideal para a chave) sobrepõe a project (committada no .mcp.json). Para apontar para outra origem da API (por exemplo, um ambiente de desenvolvimento), sobrescreva a URL localmente:

claude mcp add databolsa --scope local \
  --env DATABOLSA_API_URL=http://localhost:8081 \
  -- npx -y @databolsa/mcp

# voltar para a hospedada: re-rode o comando acima com a URL/chave hospedadas,
# ou remova o override local e deixe a config do projeto valer:
claude mcp remove databolsa -s local

Transporte HTTP

O servidor também suporta Streamable HTTP:

MCP_TRANSPORT=http MCP_HTTP_PORT=3333 npx -y @databolsa/mcp

Endpoint: http://localhost:3333/mcp.

Se você expuser o transporte HTTP na rede, coloque o processo atrás da sua própria camada de autenticação, sessão e rate-limit. O MCP em si é apenas um adaptador fino do contrato da API.

Configuração

| Variável | Default | Uso | | --- | --- | --- | | DATABOLSA_API_URL | https://api.databolsa.com | Origem da API, com ou sem /v1. | | DATABOLSA_API_KEY | vazio | Token Bearer. Obrigatório na API hospedada (api.databolsa.com). | | MCP_TRANSPORT | stdio | Use http para Streamable HTTP. | | MCP_HTTP_PORT | 3333 | Porta do transporte HTTP. | | DATABOLSA_MCP_PROFILE | vazio | Perfil da sessão (context, market, credit, account, full). Expõe só as operações das capacidades do perfil, declaradas no próprio contrato (x-profiles). Vazio = superfície completa. |

Perfis

O contrato OpenAPI declara perfis nomeados (x-profiles) e carimba cada operação com uma capacidade (x-capability). Com DATABOLSA_MCP_PROFILE=context, por exemplo, a sessão expõe apenas o grafo de objetos, documentos, eventos e saúde do serviço (~30 tools em vez de 172) — útil para agentes, que gastam menos contexto com definições de tool. Perfil desconhecido é erro no startup, com a lista dos válidos; a autorização real continua na API, por chave e escopo — o perfil reduz exposição e contexto, não é fronteira de segurança.

A API hospedada exige uma chave: crie a sua em databolsa.com/conta e exponha em DATABOLSA_API_KEY.

Exemplo de Prompt

Analise esta carteira: PETR4 100, VALE3 50, HGLG11 30.
Use as tools do DataBolsa para consultar fundamentos, proventos, preços recentes e regime macro.

As consultas de mercado são somente leitura. As operações de carteira e teses alteram dados da conta e devem ser confirmadas pelo usuário antes da chamada. O DataBolsa não executa ordens nem toma decisões de investimento.

Outra Origem Da API

Para apontar o MCP para outra origem da API DataBolsa:

DATABOLSA_API_URL=http://localhost:8081 npx -y @databolsa/mcp

Pacotes Relacionados

O SDK e a CLI expõem o mesmo contrato da API em formatos diferentes:

npm install @databolsa/sdk
npm install -g @databolsa/cli

Links

• OpenAPI: https://api.databolsa.com/openapi.json
• Fontes e cobertura: https://github.com/databolsahq/databolsa/blob/main/docs/sources.md
• Metodologia dos indicadores: https://databolsa.com/metodologia
• Limitações conhecidas: https://github.com/databolsahq/databolsa/blob/main/docs/limitations.md

Licença

Apache-2.0. O DataBolsa é infraestrutura de dados, não recomendação de investimento.