Capital.com Public API MCP Server

Capital.com MCP Server

Servidor Model Context Protocol (MCP) para a Capital.com Open API — permitindo acesso orientado por LLM à sua conta de trading na Capital.com.

⚠️ Aviso Importante

O uso da Capital.com Public API e de quaisquer ferramentas de terceiros, incluindo ferramentas baseadas em IA/LLM, é por sua conta e risco. A Capital.com é de execução exclusiva e não endossa nem se responsabiliza por softwares de terceiros ou seus resultados. Nada aqui constitui aconselhamento de investimento. Você é o único responsável por suas decisões de trading, incluindo quaisquer diferenças de preço decorrentes de latência introduzida por ferramentas de terceiros, e deve cumprir os termos e leis aplicáveis.

Derivativos de Cripto não estão disponíveis para clientes de Varejo registrados na Capital Com (UK) Ltd.

• Sempre comece com uma conta Demo antes de considerar trading ao vivo
• O trading está desabilitado por padrão e requer configuração explícita
• Todas as operações de trading exigem execução em duas fases (pré-visualização → confirmação → execução)
• Controles de risco integrados: listas de permissão, limites de tamanho, limites diários de ordens
• Use por sua conta e risco — os autores não assumem responsabilidade por perdas de trading

Para mais perguntas/esclarecimentos, consulte o FAQ: https://help.capitalccuk.com/hc/en-us/articles/34503231743506-How-to-set-up-the-Capital-com-MCP-Server

Guia de Início Rápido

Passo 1: Obter Credenciais da API da Capital.com

1. Criar Conta: Acesse capital.com/trading/signup

   • Escolha uma conta Demo para testes (recomendado)
   • Verifique seu e-mail

2. Ativar 2FA: Configurações > Segurança > Autenticação de Dois Fatores

   • Necessário antes de gerar chaves de API

3. Gerar Chave de API: Configurações > Integrações de API > Gerar nova chave

   • Defina um rótulo (ex.: "MCP Server")
   • Defina uma senha personalizada (esta NÃO é a senha da sua plataforma)
   • Salve a chave de API exibida (exibida apenas uma vez!)
   • Observação: as chaves de API têm capacidade de trading; a Capital.com não oferece chaves somente leitura

Passo 2: Instalar e Configurar

Instalação Guiada por IA: Abra esta pasta do projeto em um editor com IA (Claude Code, Cursor, Windsurf) e peça para instalar o servidor MCP da Capital.com — ele seguirá o INSTALL.md para orientá-lo na configuração, escolhendo o melhor método para o seu ambiente.

Você também tem estas opções de instalação manual:

Opção A: Instalação com Um Clique via Pacote MCPB (Recomendado)

O repositório inclui um pacote capital-mcp.mcpb pré-construído — abra-o no Claude Desktop e pronto, sem necessidade de editar a configuração manualmente.

Passos:

1. Clone o repositório:

   git clone https://github.com/capital-com-sv/capital-mcp.git
   cd capital-mcp
   

2. Abra o capital-mcp.mcpb no Claude Desktop (clique duas vezes ou arraste-o para o aplicativo).
3. O Claude Desktop solicitará suas credenciais (chave de API, identificador, senha) e controles de trading. Preencha-os e clique em Instalar.
4. Reinicie o Claude Desktop e verifique perguntando: "Quais ferramentas da Capital.com estão disponíveis?"

Opção B: Instalação Manual via Script

Pré-requisitos: Python 3.10+ e Git devem estar instalados.

• macOS: brew install python3 git
• Ubuntu/Debian: sudo apt install python3 python3-venv git
• Windows: python.org (marque "Add to PATH" durante a instalação) + git-scm.com

Mac/Linux:

cd /path/to/capital-mcp
./install.sh

Windows (PowerShell):

cd C:\path\to\capital-mcp
pwsh install.ps1

O script de instalação criará um ambiente virtual, instalará as dependências e imprimirá a configuração do cliente MCP para você.

Edite o .env com suas credenciais:

# Required
CAP_ENV=demo
CAP_API_KEY=your_generated_api_key_here
CAP_IDENTIFIER=your_email@example.com
CAP_API_PASSWORD=your_custom_api_password

# Trading controls (keep trading disabled until ready)
CAP_ALLOW_TRADING=false
CAP_ALLOWED_EPICS=

# Optional: enable later for real trading
# CAP_ALLOW_TRADING=true
# CAP_ALLOWED_EPICS=SILVER,GOLD,BTCUSD

Opção C: Docker

Pré-requisitos: Docker deve estar instalado.

1. Crie um arquivo .env com suas credenciais (veja .env.example):

   CAP_ENV=demo
   CAP_API_KEY=your_api_key_here
   CAP_IDENTIFIER=your_email@example.com
   CAP_API_PASSWORD=your_custom_password
   CAP_ALLOW_TRADING=false
   

2. Execute o servidor:

   docker run -i --rm --env-file .env ghcr.io/capital-com-sv/capital-mcp:latest
   

Solução de Problemas: Verificar Logs

Se você encontrar problemas ao usar o servidor MCP com o Claude Desktop ou outros clientes, verifique os arquivos de log:

macOS:

# View MCP server logs
tail -f ~/Library/Logs/Claude/mcp-server-capital-com.log

# Search for errors
grep -i error ~/Library/Logs/Claude/mcp-server-capital-com.log

Linux:

tail -f ~/.config/Claude/logs/mcp-server-capital-com.log

Windows:

Get-Content $env:APPDATA\Claude\logs\mcp-server-capital-com.log -Wait

---

Integração com Clientes

Para configuração específica de cliente (Claude Desktop, Claude Code, Cursor, Windsurf, Codex, Docker, clientes personalizados), consulte USAGE.md — Integração com Clientes.

Exemplos de Uso

Exemplo de Conversa com o Claude Desktop

You: "Check my Capital.com session status"

Claude: I'll check your session status.
[Calls cap_session_status]
Response: {"ok": true, "data": {"env": "demo", "logged_in": false, ...}}

You're not currently logged in to the demo environment.

---

You: "Login to my Capital.com account"

Claude: I'll log you in.
[Calls cap_session_login]
Success! Logged in to account ID: ABC123

---

You: "Search for Bitcoin markets"

Claude: Searching for Bitcoin...
[Calls cap_market_search with search_term="Bitcoin"]
Found 5 markets:
- BTCUSD: Bitcoin vs US Dollar
- BTCEUR: Bitcoin vs Euro
- BTCGBP: Bitcoin vs British Pound
...

---

You: "Show me current positions"

Claude: Let me check your positions.
[Calls cap_trade_positions_list]
You have no open positions.

---

You: "Preview buying 1.0 SILVER"

Claude: I'll preview this trade. Note: Trading is currently DISABLED.
[Calls cap_trade_preview_position]
Preview failed: Trading is disabled (CAP_ALLOW_TRADING=false)

To enable trading, update your .env file:
CAP_ALLOW_TRADING=true
CAP_ALLOWED_EPICS=SILVER

Fluxo de Execução de Trading (Quando o Trading Está Habilitado)

1. Preview the trade (validates everything, no side effects):
   "Preview buying 2.0 SILVER with stop at 24.50"
   → Returns preview_id

2. Review the preview results:
   - Normalized size (rounded to broker increments)
   - Risk checks (allowlist, size limits, daily limits)
   - Estimated entry price

3. Execute ONLY if all checks pass:
   "Execute position with preview_id [id], confirm=true"
   → Creates real position
   → Returns deal_reference
   → Polls for broker confirmation

4. Monitor:
   "Show my positions"
   "Close position [deal_id] with confirm=true"

Referência de Variáveis de Ambiente

Obrigatórias

• CAP_ENV - Ambiente: demo ou live (padrão: demo)
• CAP_API_KEY - Chave de API da Capital.com
• CAP_IDENTIFIER - E-mail de login
• CAP_API_PASSWORD - Senha personalizada da chave de API

Controles de Risco (Recomendados)

• CAP_ALLOW_TRADING - Habilitar trading (padrão: false)
• CAP_ALLOWED_EPICS - Lista de permissão separada por vírgulas (ex.: "SILVER,GOLD,BTCUSD") ou "ALL" para irrestrito
• CAP_MAX_POSITION_SIZE - Tamanho máximo de posição (padrão: 1.0)
• CAP_MAX_WORKING_ORDER_SIZE - Tamanho máximo de ordem (padrão: 1.0)
• CAP_MAX_OPEN_POSITIONS - Máximo de posições simultâneas (padrão: 3)
• CAP_MAX_ORDERS_PER_DAY - Limite diário de ordens (padrão: 20)
• CAP_REQUIRE_EXPLICIT_CONFIRM - Exigir confirm=true (padrão: true)
• CAP_DRY_RUN - Bloquear todas as execuções de trading (padrão: false)

Opcionais

• CAP_DEFAULT_ACCOUNT_ID - Conta padrão após o login
• CAP_HTTP_TIMEOUT_S - Timeout HTTP (padrão: 15)
• CAP_LOG_LEVEL - Nível de log: DEBUG, INFO, WARNING, ERROR (padrão: INFO)

Recursos do MCP

38 ferramentas em 6 categorias, 7 prompts de fluxo de trabalho e 4 recursos somente leitura.

Categoria	Ferramentas	Descrição
Sessão	4	Login, logout, status, keep-alive
Dados de Mercado	6	Pesquisa, detalhes, preços, sentimento, navegação
Conta	6	Listar contas, preferências, histórico de atividade/transações, recarga de demo
Trading	13	Pré-visualizar, executar, fechar posições; listar/cancelar/alterar ordens pendentes; confirmações
Listas de Observação	6	Criar, listar, obter, excluir listas de observação; adicionar/remover mercados
Streaming	3	Preços em tempo real, alertas, P&L de carteira via WebSocket

Prompt	Descrição
market_scan	Verificar uma lista de observação em busca de condições de trading
trade_proposal	Planejar uma operação com dimensionamento baseado em risco (somente pré-visualização)
execute_trade	Executar uma operação previamente pré-visualizada
position_review	Analisar posições abertas e exposição (somente leitura)
live_price_monitor	Acompanhamento de preços em tempo real com alertas de movimento (WebSocket)
real_time_alerts	Alertas condicionais de níveis de preço (WebSocket)
live_portfolio_monitor	Painel de P&L da carteira em tempo real (WebSocket)

Recurso	Descrição
cap://status	Saúde do servidor, estado da sessão, limites de taxa
cap://risk-policy	Configuração de gestão de risco e camadas de validação
cap://allowed-epics	Configuração da lista de permissão de trading
cap://market-cache/{epic}	Detalhes de mercado em cache (busca ao vivo)

Para detalhes completos, parâmetros e exemplos, consulte USAGE.md.

Processo de Execução de Trading

Execução Obrigatória em Duas Etapas

Todas as operações com efeitos colaterais usam um fluxo estrito de pré-visualização → execução:

1. Pré-visualização: Valida a operação contra as regras da corretora + política de risco local

   • Retorna preview_id com a requisição normalizada + verificações de risco
   • Sem efeitos colaterais, validação somente leitura

2. Execução: Envia a operação usando preview_id

   • Reexecuta verificações críticas
   • Requer confirm=true se CAP_REQUIRE_EXPLICIT_CONFIRM=true
   • Verifica a confirmação da corretora
   • Incrementa o contador diário de ordens

Controles de Risco

• Lista de Permissão: Somente EPICs em CAP_ALLOWED_EPICS podem ser negociados
• Limites de Tamanho: Tamanho máximo de posição/ordem aplicado
• Limites de Posição: Máximo de posições abertas a qualquer momento
• Limites Diários: Máximo de ordens por dia
• Normalização de Tamanho: Arredonda para o mínimo/máximo/incremento da corretora
• Modo Simulado (Dry-Run): Bloqueia todas as execuções quando habilitado

Documentação

• Guia de Uso: USAGE.md - Guia de uso abrangente com exemplos
• Referência da API da Capital.com: https://open-api.capital.com/
• Coleção Postman da API da Capital.com: https://github.com/capital-com-sv/capital-api-postman

Licença

MIT

Política de Privacidade

O servidor MCP da Capital.com é executado localmente na sua máquina e comunica-se diretamente com a Capital.com Public API usando as credenciais que você fornece. Ele não opera como um serviço hospedado e não possui servidores próprios.

Coleta de dados

O servidor MCP não coleta nem armazena nenhum dado. Ele atua como uma ponte local entre seu cliente de IA e a Capital.com Public API.

Uso e armazenamento de dados

Todos os dados trocados durante uma sessão são processados em memória na sua máquina local e descartados quando a sessão termina. Nenhum dado é gravado em disco pelo servidor MCP. Observação: seu cliente de IA pode processar, registrar ou armazenar dados transmitidos por ele, de acordo com sua própria política de privacidade, que você deve revisar separadamente.

Compartilhamento com terceiros

O servidor MCP não compartilha dados com terceiros. Os dados fluem apenas entre seu ambiente local e a Capital.com Public API, sujeitos à Política de Privacidade da própria Capital.com.

Retenção de dados

O servidor MCP não retém nenhum dado. Os dados da sessão existem apenas em memória durante a sessão.

Credenciais de API

As credenciais de API que você fornece são armazenadas e gerenciadas no seu ambiente local. Você é responsável por protegê-las adequadamente.

Contato

Para consultas relacionadas à privacidade sobre sua conta na Capital.com ou sobre como a Capital.com trata seus dados, consulte a Política de Privacidade da Capital.com ou entre em contato com support@capital.com.

Aviso Legal – Uso da Capital.com Public API com Ferramentas de Terceiros

Integração com Terceiros

Esta página descreve como os clientes podem conectar a Capital.com Public API a softwares, ferramentas ou integrações de terceiros, incluindo aqueles alimentados por inteligência artificial ou grandes modelos de linguagem ('LLMs'). Qualquer software, ferramenta ou integração de terceiros é independente da Capital.com e não faz parte dos serviços da Capital.com. A Capital.com não controla, desenvolve, endossa nem aceita qualquer responsabilidade por qualquer software de terceiros, sua funcionalidade, resultados ou quaisquer consequências decorrentes do seu uso. Qualquer uso de ferramentas ou integrações de terceiros em conexão com a Capital.com Public API é inteiramente por sua conta e risco. Você é responsável por revisar os termos, políticas de privacidade e práticas de tratamento de dados de qualquer ferramenta de terceiros que escolher usar.

Uso da Public API

O uso da Capital.com Public API é inteiramente a seu critério e risco. A Capital.com disponibiliza a Public API para fins informativos e de trading, mas não recomenda, endossa ou incentiva qualquer uso, integração ou estratégia de trading específica. Você é o único responsável por como acessa e usa a API, incluindo os parâmetros de quaisquer ordens enviadas, a configuração de quaisquer ferramentas ou sistemas conectados e a interpretação de quaisquer dados recebidos. A Capital.com não aceita responsabilidade por perdas ou resultados não intencionais decorrentes do uso da API, seja acessada diretamente ou por meio de ferramentas de terceiros. A disponibilidade, funcionalidade e especificações da API podem ser modificadas, limitadas por taxa, suspensas ou descontinuadas a qualquer momento sem aviso prévio. O uso da Public API está sujeito aos Termos e Condições e aos Termos de Trading Eletrônico da Capital.com, que você deve ler cuidadosamente antes de usar a API.

Serviço de Execução Exclusiva e Sem Aconselhamento de Investimento

A Capital.com fornece seus serviços com base em execução exclusiva. A negociação de instrumentos financeiros envolve risco significativo de perda. Nada nesta página, na Public API ou em qualquer software ou integração de terceiros constitui aconselhamento de investimento, recomendação pessoal ou solicitação para comprar ou vender qualquer instrumento financeiro. Isso inclui qualquer saída, sinal, sugestão ou análise gerada por IA, ferramentas baseadas em LLM ou outras ferramentas automatizadas. Todas as decisões de trading, incluindo qualquer atividade automatizada ou algorítmica, são tomadas por sua conta e risco e permanecem como sua única responsabilidade. A Capital.com não controla as saídas de ferramentas de IA ou LLM de terceiros conectadas à Public API e não pode garantir que tais ferramentas não gerarão conteúdo que possa ser interpretado como aconselhamento de investimento ou recomendação pessoal. Qualquer saída desse tipo não é fornecida pela Capital.com nem em seu nome e não deve ser considerada como aconselhamento.

Riscos da Negociação Automatizada e Algorítmica

O uso da Public API em conexão com ferramentas de negociação automatizada ou algorítmica acarreta riscos adicionais, incluindo, mas não se limitando a: execução rápida de ordens sem revisão ou intervenção humana; erros de sistema, falhas de software ou problemas de conectividade; execução a preços materialmente diferentes dos esperados; e ordens não intencionais ou errôneas resultantes de ferramentas ou parâmetros mal configurados. A Capital.com não é responsável por quaisquer perdas decorrentes desses riscos ou da interação entre seus sistemas e quaisquer ferramentas de terceiros. O desempenho passado e quaisquer resultados gerados por ferramentas automatizadas não são indicativos de resultados futuros.

Quando ferramentas baseadas em IA ou LLM são usadas para recuperar dados de mercado ou informações de preços, pode haver um atraso entre o preço comunicado pela ferramenta e o preço pelo qual qualquer ordem resultante é executada. Todas as ordens colocadas através da Public API são executadas como ordens de mercado. O preço de execução pode, portanto, diferir de qualquer preço exibido no momento de uma solicitação. A Capital.com busca alcançar a melhor execução de acordo com suas obrigações; não aceitamos responsabilidade por diferenças de preço decorrentes de latência atribuível a ferramentas ou sistemas de terceiros fora de seu controle.

Uso Proibido

O uso da Public API e de quaisquer ferramentas conectadas não deve ser usado para manipular a plataforma da Capital.com, explorar preços ou latência, envolver-se em abuso de mercado ou obter qualquer vantagem injusta. A Capital.com reserva-se o direito de restringir, suspender ou encerrar o acesso à API e/ou à sua conta quando considerar razoavelmente que tal uso indevido ocorreu ou é provável que ocorra. Os clientes não devem permitir que terceiros exerçam controle discricionário sobre suas contas.

Suas Responsabilidades

Você é responsável por garantir que seu uso da plataforma Capital.com, da Public API e de quaisquer ferramentas ou integrações de terceiros esteja em conformidade com os Termos e Condições da Capital.com, os Termos de Negociação Eletrônica e todas as leis e regulamentos aplicáveis em sua jurisdição. Você deve considerar cuidadosamente se as ferramentas de negociação automatizada são apropriadas para suas circunstâncias, experiência e tolerância a risco antes de usá-las. A Capital.com recomenda fortemente que você teste minuciosamente quaisquer ferramentas ou integrações automatizadas usando uma conta demo antes de conectá-las a um ambiente de negociação ao vivo.