IBKR MCP

Servidor MCP do Interactive Brokers

AVISO: Este é um servidor MCP não oficial, desenvolvido pela comunidade e NÃO é afiliado ou endossado pela Interactive Brokers. Este software está em estado Alpha e pode não funcionar perfeitamente.

Um servidor Model Context Protocol (MCP) que fornece integração com a plataforma de negociação da Interactive Brokers. Este servidor permite que assistentes de IA interajam com sua conta IB para obter dados de mercado, verificar posições e realizar negociações.

🔒 Aviso de Segurança

Recursos

• Integração com a API da Interactive Brokers: Capacidades completas de negociação, incluindo gerenciamento de conta, rastreamento de posições, dados de mercado em tempo real e gerenciamento de ordens (ordens de mercado, limite e stop)
• Suporte a Flex Query: Execute Flex Queries para recuperar extratos de conta, confirmações de negociação e dados históricos. As consultas são automaticamente lembradas para fácil reutilização
• Autenticação Flexível: Escolha entre autenticação OAuth baseada em navegador ou modo headless com credenciais para ambientes automatizados, incluindo substituição totalmente automatizada de 2FA via TOTP. Consulte o Documento de Estratégia TOTP 2FA para configuração detalhada e avisos de risco importantes.
• Configuração Simples: Execute diretamente com npx - sem necessidade de Docker ou instalações adicionais. Inclui IB Gateway pré-configurado e runtime Java para todas as plataformas

Aviso de Segurança

AVISOS IMPORTANTES:

• Risco Financeiro: Negociação envolve risco substancial de perda. Sempre teste com conta demo primeiro.
• Segurança: Este software lida com dados financeiros sensíveis. Execute apenas localmente, nunca em servidores públicos.
• Sem Garantia: Este software não oficial não oferece garantias. Use por sua conta e risco.
• Não é Aconselhamento Financeiro: Esta ferramenta é apenas para automação, não aconselhamento financeiro.

Pré-requisitos

Nenhuma instalação adicional necessária para plataformas principais. Este pacote inclui:

• IB Gateway pré-configurado para todas as plataformas (Linux, macOS, Windows)
• Ambiente de Execução Java (JRE) para macOS, Windows e builds Linux padrão
• Download automático do JRE musl no primeiro uso para contêineres baseados em Alpine (ex.: node:lts-alpine, supergateway)
• Todas as dependências necessárias

Você só precisa de:

• Conta na Interactive Brokers (negociação demo ou real)
• Node.js 18+ (para executar o servidor MCP)

Início Rápido

Adicione este servidor MCP à sua configuração do Cursor/Claude:

{
  "mcpServers": {
    "interactive-brokers": {
      "command": "npx",
      "args": ["-y", "interactive-brokers-mcp"]
    }
  }
}

Ao usar o servidor pela primeira vez, uma janela de navegador será aberta automaticamente para o fluxo de autenticação OAuth da Interactive Brokers. Faça login com suas credenciais IB para autorizar a conexão.

Configuração do Modo Headless

Para ambientes automatizados ou quando você preferir não usar um navegador para autenticação, você pode ativar o modo headless configurando-o na sua configuração do servidor MCP:

{
  "mcpServers": {
    "interactive-brokers": {
      "command": "npx",
      "args": ["-y", "interactive-brokers-mcp"],
      "env": {
        "IB_HEADLESS_MODE": "true",
        "IB_USERNAME": "your_ib_username",
        "IB_PASSWORD_AUTH": "your_ib_password"
      }
    }
  }
}

No modo headless, o servidor autenticará automaticamente usando suas credenciais sem abrir uma janela de navegador. Isso é útil para:

• Sistemas de negociação automatizados
• Ambientes de servidor sem display
• Pipelines de CI/CD
• Situações em que a interação com o navegador não é desejada

Importante: Mesmo no modo headless, a Interactive Brokers pode exigir autenticação de dois fatores (2FA). Quando o 2FA é acionado, a autenticação headless aguardará até 60 segundos para você concluir o processo de 2FA através do seu método configurado (aplicativo móvel, SMS, etc.) antes de retornar uma resposta AUTHENTICATION_PENDING. Aguarde a aprovação ser concluída e depois verifique as informações da conta novamente.

Para ativar a negociação demo, adicione "IB_PAPER_TRADING": "true" às suas variáveis de ambiente:

{
  "mcpServers": {
    "interactive-brokers": {
      "command": "npx",
      "args": ["-y", "interactive-brokers-mcp"],
      "env": {
        "IB_HEADLESS_MODE": "true",
        "IB_USERNAME": "your_ib_username",
        "IB_PASSWORD_AUTH": "your_ib_password",
        "IB_PAPER_TRADING": "true"
      }
    }
  }
}

Nota de Segurança: Armazene as credenciais com segurança e nunca as envie para o controle de versão. Considere usar arquivos de variáveis de ambiente ou sistemas seguros de gerenciamento de credenciais.

Configuração de Flex Query (Opcional)

Para usar Flex Queries para recuperar extratos de conta e dados históricos, você precisa configurar seu Token do Flex Web Service:

{
  "mcpServers": {
    "interactive-brokers": {
      "command": "npx",
      "args": ["-y", "interactive-brokers-mcp"],
      "env": {
        "IB_FLEX_TOKEN": "your_flex_token_here"
      }
    }
  }
}

Como Obter Seu Token Flex:

1. Faça login no Gerenciamento de Conta da Interactive Brokers
2. Vá para Configurações → Configurações da Conta
3. Navegue até Relatórios → Flex Web Service
4. Gere ou recupere seu Token do Flex Web Service

Para instruções detalhadas sobre como ativar o Flex Web Service, consulte o Guia do IB Flex Web Service.

Criando Flex Queries:

1. Vá para Relatórios → Flex Queries no Gerenciamento de Conta
2. Crie ou personalize seu modelo de consulta
3. Clique no ícone de informações ao lado da sua consulta para encontrar seu ID de Consulta

Para um guia completo sobre como criar e personalizar Flex Queries, consulte o Guia de Flex Queries do IB.

Nota: Quando você executa uma Flex Query pela primeira vez, o servidor MCP a salva automaticamente com o nome da API. Execuções futuras podem referenciar a consulta pelo seu ID ou pelo nome salvo.

Recursos da Flex Query:

• Memória Automática: Quando você executa uma Flex Query, ela é salva automaticamente para uso futuro
• Reutilização Fácil: Consultas usadas anteriormente são lembradas - sem necessidade de copiar IDs de consulta repetidamente
• Nomes Amigáveis: Opcionalmente, forneça um nome amigável ao executar uma consulta pela primeira vez
• Esquecer Consultas: Remova consultas que você não precisa mais com a ferramenta forget_flex_query

Variáveis de Configuração

Recurso	Variável de Ambiente	Argumento de Linha de Comando
Nome de usuário	IB_USERNAME	--ib-username
Senha	IB_PASSWORD_AUTH	--ib-password-auth
Modo Headless	IB_HEADLESS_MODE	--ib-headless-mode
Negociação Demo	IB_PAPER_TRADING	--ib-paper-trading
Tempo Limite de Autenticação	IB_AUTH_TIMEOUT	--ib-auth-timeout
Segundos de Espera de Autenticação	IB_AUTH_WAIT_SECONDS	--ib-auth-wait-seconds
Segundos de Polling de Autenticação	IB_AUTH_POLL_SECONDS	--ib-auth-poll-seconds
Forçar gateway empacotado independente	IB_FORCE_STANDALONE_GATEWAY	N/A
Token Flex	IB_FLEX_TOKEN	N/A
Modo somente leitura	IB_READ_ONLY_MODE	--ib-read-only-mode
Estratégia 2FA	IB_TWO_FA_STRATEGY	N/A
Chave Secreta TOTP	IB_TOTP_SECRET	N/A
Substituições de seletor da página de login	IB_SELECTOR_USERNAME, IB_SELECTOR_PASSWORD, IB_SELECTOR_LOGIN_SUBMIT	N/A
Substituições de seletor do formulário TOTP	IB_SELECTOR_TOTP_INPUT, IB_SELECTOR_TOTP_SUBMIT	N/A

Consulte o Documento de Estratégia TOTP 2FA para detalhes sobre as variáveis de 2FA e substituição de seletor.

Ciclo de Vida do Gateway

Na inicialização, o MCP primeiro verifica endpoints locais do Gateway alcançáveis na porta configurada e nas portas comuns do Client Portal Gateway. Se um Gateway existente e saudável for encontrado, o MCP se conecta a ele e não inicia outro Gateway empacotado.

Quando nenhum Gateway existente adequado está acessível, o MCP inicia o Gateway Java empacotado como um processo destacado durável. Os arquivos de coordenação de runtime são armazenados em ib-gateway/.runtime/:

• gateway-session.json registra o pid, porta, versão e caminhos de log do Gateway gerenciado pelo MCP.
• gateway-session.lock impede que dois processos MCP iniciem Gateways gerenciados duplicados ao mesmo tempo.
• gateway.stdout.log e gateway.stderr.log recebem a saída do processo do Gateway.

O desligamento normal do MCP desconecta do Gateway e o deixa em execução para que execuções MCP posteriores possam reutilizá-lo. Se IB_FORCE_STANDALONE_GATEWAY=true estiver definido, o MCP ignora a descoberta de Gateways externos não relacionados, mas ainda reutiliza ou coordena através dos metadados de sessão e arquivos de bloqueio gerenciados pelo MCP.

Para redefinir a sessão do Gateway gerenciado, pare o processo do Gateway registrado em ib-gateway/.runtime/gateway-session.json, depois remova ib-gateway/.runtime/gateway-session.json e qualquer ib-gateway/.runtime/gateway-session.lock desatualizado. O MCP remove automaticamente metadados desatualizados quando o pid registrado não existe mais.

Ferramentas MCP Disponíveis

Negociação e Gerenciamento de Conta

Ferramenta	Descrição
get_account_info	Recuperar informações da conta e saldos
get_positions	Obter posições atuais e P&L
get_market_data	Dados de mercado em tempo real para símbolos
place_order	Colocar ordens de mercado, limite ou stop (somente se o modo somente leitura estiver desativado)
get_order_status	Verificar status de execução de ordens
get_live_orders	Obter todas as ordens ativas/abertas para monitoramento

Flex Queries (Requer IB_FLEX_TOKEN)

Ferramenta	Descrição
get_flex_query	Executar uma Flex Query e recuperar extratos (salva automaticamente para reutilização)
list_flex_queries	Listar todas as Flex Queries usadas anteriormente
forget_flex_query	Remover uma Flex Query salva da memória

Solução de Problemas

Problemas de Autenticação:

• Use a interface web que abre automaticamente
• Complete qualquer autenticação de dois fatores necessária
• Tente o modo de negociação demo se a negociação real falhar

Problemas de Descoberta do Gateway:

• Se outro IB Gateway já estiver escutando em uma porta local, mas não deve ser reutilizado, defina IB_FORCE_STANDALONE_GATEWAY=true
• Gateways existentes só são reutilizados quando o processo MCP pode alcançá-los via HTTPS; caso contrário, o gateway independente empacotado é iniciado em uma porta disponível
• Para problemas de inicialização do Gateway gerenciado pelo MCP, inspecione ib-gateway/.runtime/gateway.stdout.log, ib-gateway/.runtime/gateway.stderr.log e ib-gateway/.runtime/gateway-session.json
• Para limpar um bloqueio de inicialização gerenciado desatualizado, confirme que nenhum processo MCP está iniciando o Gateway atualmente e depois remova ib-gateway/.runtime/gateway-session.lock

Suporte

• Este Servidor: Abra uma issue neste repositório.

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

Agradecimentos aos nossos colaboradores

Um grande agradecimento a todos que contribuíram para tornar este projeto melhor.