Capital.com Public API MCP Server

Servidor MCP da Capital.com

Servidor Model Context Protocol (MCP) para a Capital.com Open API — permitindo acesso orientado por LLM à sua conta de negociação 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 é somente de execução e não endossa nem se responsabiliza por software de terceiros ou seus resultados. Nada aqui é aconselhamento de investimento. Você é o único responsável por suas decisões de negociação, 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 negociação ao vivo
• A negociação está habilitada por padrão e pode ser desabilitada na configuração
• Todas as operações de negociação 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 em negociações

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: Obtenha as Credenciais da API da Capital.com

1. Crie uma Conta: Acesse capital.com/trading/signup

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

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

   • Necessário antes de gerar chaves de API

3. Gere a 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 negociação; a Capital.com não oferece chaves somente leitura

Passo 2: Instale e Configure

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 edição manual de configuração.

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á as credenciais (chave de API, identificador, senha) e os controles de negociação. 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 "Adicionar ao 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 exibirá 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
CAP_ALLOW_TRADING=true
CAP_ALLOWED_EPICS=ALL

# Optional: enable later for real trading
# CAP_ALLOW_TRADING=true
# Narrow the allowlist to the instruments you actually trade
# 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: Verifique os 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 Negociação (Quando a Negociação Está Habilitada)

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 negociação (padrão: true)
• CAP_ALLOWED_EPICS - Instrumentos nos quais a negociação é permitida (padrão: ALL, todos os instrumentos). Restrinja com uma lista separada por vírgulas, ex.: "SILVER,GOLD,BTCUSD". Vazio bloqueia toda a negociação
• 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 negociação (padrão: false)

Opcionais

• CAP_DEFAULT_ACCOUNT_ID - Conta padrão após o login
• CAP_HTTP_TIMEOUT_S - Tempo limite de 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	Busca, detalhes, preços, sentimento, navegação
Conta	6	Listar contas, preferências, histórico de atividades/transações, recarga de demo
Negociação	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 portfólio via WebSocket

Prompt	Descrição
market_scan	Escanear uma lista de observação para condições de negociação
trade_proposal	Planejar uma negociação com dimensionamento baseado em risco (somente pré-visualização)
execute_trade	Executar uma negociaçã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 de portfólio ao vivo (WebSocket)

Recurso	Descrição
cap://status	Saúde do servidor, estado da sessão, limites de taxa
cap://risk-policy	Configuração de gerenciamento de risco e camadas de validação
cap://allowed-epics	Configuração da lista de permissão de negociação
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 Negociação

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 negociação contra as regras do corretor + política de risco local

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

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

   • Reexecuta verificações críticas
   • Exige confirm=true se CAP_REQUIRE_EXPLICIT_CONFIRM=true
   • Consulta a confirmação do corretor
   • Incrementa o contador diário de ordens

Controles de Risco

• Lista de Permissão: Somente EPICs em CAP_ALLOWED_EPICS podem ser negociados; o ALL padrão permite todos os instrumentos
• 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 mínimo/máximo/incremento do corretor
• Modo de Simulação: 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 se comunica 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 dados. 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 dados. Os dados da sessão existem apenas em memória durante a duração da sessão.

Credenciais da API

As credenciais da 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 software, 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 software de terceiros, sua funcionalidade, resultados ou quaisquer consequências decorrentes de 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

Seu 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 negociação, mas não recomenda, endossa nem incentiva qualquer uso, integração ou estratégia de negociação 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 seu 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. Seu uso da Public API está sujeito aos Termos e Condições e aos Termos de Negociação Eletrônica da Capital.com, que você deve ler atentamente antes de usar a API.

Serviço de Execução Apenas e Ausência de Consultoria de Investimento

A Capital.com fornece seus serviços com base exclusiva de execução. Negociar instrumentos financeiros envolve risco significativo de perda. Nada nesta página, na Public API, ou em qualquer software ou integração de terceiros constitui consultoria 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 negociação, incluindo qualquer atividade automatizada ou algorítmica, são tomadas por sua conta e risco e permanecem de sua exclusiva 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 consultoria de investimento ou recomendação pessoal. Qualquer saída desse tipo não é fornecida pela Capital.com ou em seu nome e não deve ser utilizada como aconselhamento.

Riscos de 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 de tais riscos ou da interação entre seus sistemas e quaisquer ferramentas de terceiros. Desempenho passado e quaisquer saídas geradas por ferramentas automatizadas não são indicativos de resultados futuros.

Quando ferramentas baseadas em IA ou LLM são usadas para obter 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 por meio da Public API são executadas como ordens a 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 nosso controle.

Uso Proibido

O uso da Public API e de quaisquer ferramentas conectadas não deve ser utilizado 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 da 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 ferramentas de negociação automatizada são adequadas às suas circunstâncias, experiência e tolerância a risco antes de usá-las. A Capital.com recomenda fortemente que você teste quaisquer ferramentas ou integrações automatizadas minuciosamente usando uma conta Demo antes de conectá-las a um ambiente de negociação ao vivo.