MetaTrader MCP Server

Um servidor MCP baseado em Python que permite que LLMs de IA executem negociações na plataforma MetaTrader 5.

GitHub

795

Experimente este MCPPatrocinado

Documentação

MetaTrader MCP Server

Deixe assistentes de IA negociarem por você usando linguagem natural

MetaTrader MCP Server

📑 Sumário

O que é isso?
Recursos
Para quem é?
Aviso importante
Pré-requisitos
Início rápido
Habilidade do Assistente de Negociação
Exemplos de uso
Operações disponíveis
Servidor de Cotações WebSocket
Configuração avançada
Roteiro
Desenvolvimento
Contribuindo
Documentação
Obtendo ajuda
Licença

🌟 O que é isso?

O MetaTrader MCP Server é uma ponte que conecta assistentes de IA (como Claude, ChatGPT) à plataforma de negociação MetaTrader 5. Em vez de clicar em botões, você pode simplesmente dizer ao seu assistente de IA o que fazer:

"Mostre meu saldo da conta" "Compre 0,01 lotes de EUR/USD" "Feche todas as posições lucrativas"

A IA entende sua solicitação e a executa no MetaTrader 5 automaticamente.

Como funciona

You → AI Assistant → MCP Server → MetaTrader 5 → Your Trades

✨ Recursos

🗣️ Negociação por linguagem natural - Fale com a IA em português simples para executar negociações
🤖 Suporte a múltiplas IAs - Funciona com Claude Desktop, ChatGPT (via Open WebUI) e outros
📊 Acesso total ao mercado - Obtenha preços em tempo real, dados históricos e informações de símbolos
💼 Controle completo da conta - Verifique saldo, patrimônio, margem e estatísticas de negociação
⚡ Gerenciamento de ordens - Coloque, modifique e feche ordens com comandos simples
🔒 Seguro - Todas as credenciais permanecem na sua máquina
🌐 Interfaces flexíveis - Use como servidor MCP, API REST ou fluxo WebSocket
📖 Bem documentado - Guias e exemplos abrangentes

🎯 Para quem é?

Traders que desejam automatizar suas negociações usando IA
Desenvolvedores que criam bots de negociação ou ferramentas de análise
Analistas que precisam de acesso rápido a dados de mercado
Qualquer pessoa interessada em combinar IA com mercados financeiros

⚠️ Aviso importante

Leia isto com atenção:

Negociar instrumentos financeiros envolve risco significativo de perda. Este software é fornecido como está, e os desenvolvedores não assumem nenhuma responsabilidade por quaisquer perdas, ganhos ou consequências decorrentes do uso deste software.

Ao usar este software, você reconhece que:

Você entende os riscos da negociação financeira
Você é responsável por todas as negociações executadas através deste sistema
Você não responsabilizará os desenvolvedores por quaisquer resultados
Você está usando este software por sua conta e risco

Isto não é aconselhamento financeiro. Sempre negocie com responsabilidade.

📋 Pré-requisitos

Antes de começar, certifique-se de ter:

Python 3.10 ou superior - Baixe aqui
Terminal MetaTrader 5 - Baixe aqui
Conta de negociação MT5 - Credenciais de conta demo ou real
- Número de login
- Senha
- Nome do servidor (ex.: "MetaQuotes-Demo")

🚀 Início rápido

Passo 1: Instale o pacote

Abra seu terminal ou prompt de comando e execute:

pip install metatrader-mcp-server

Passo 2: Ative a negociação algorítmica

Abra o MetaTrader 5
Vá para Tools → Options
Clique na aba Expert Advisors
Marque a caixa para Allow algorithmic trading
Clique em OK

Passo 3: Escolha sua interface

Escolha uma com base em como você deseja usar:

Opção A: Usar com Claude Desktop (STDIO local)

Encontre o arquivo de configuração do Claude Desktop:
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
Abra o arquivo e adicione esta configuração:

{
  "mcpServers": {
    "metatrader": {
      "command": "metatrader-mcp-server",
      "args": [
        "--login",     "YOUR_MT5_LOGIN",
        "--password",  "YOUR_MT5_PASSWORD",
        "--server",    "YOUR_MT5_SERVER",
        "--transport", "stdio"
      ]
    }
  }
}

Opcional: Especifique um caminho personalizado do terminal MT5

Se o seu terminal MT5 estiver instalado em um local não padrão, adicione o argumento --path:

{
  "mcpServers": {
    "metatrader": {
      "command": "metatrader-mcp-server",
      "args": [
        "--login",     "YOUR_MT5_LOGIN",
        "--password",  "YOUR_MT5_PASSWORD",
        "--server",    "YOUR_MT5_SERVER",
        "--transport", "stdio",
        "--path",      "C:\\Program Files\\MetaTrader 5\\terminal64.exe"
      ]
    }
  }
}

Substitua YOUR_MT5_LOGIN, YOUR_MT5_PASSWORD e YOUR_MT5_SERVER pelas suas credenciais reais
Reinicie o Claude Desktop
Comece a conversar! Experimente: "Qual é o saldo da minha conta?"

Opção B: Usar com Open WebUI (Para ChatGPT e outros LLMs)

Inicie o servidor HTTP:

metatrader-http-server --login YOUR_LOGIN --password YOUR_PASSWORD --server YOUR_SERVER --host 0.0.0.0 --port 8000

Opcional: Especifique um caminho personalizado do terminal MT5

Se o seu terminal MT5 estiver instalado em um local não padrão, adicione o argumento --path:

metatrader-http-server --login YOUR_LOGIN --password YOUR_PASSWORD --server YOUR_SERVER --path "C:\Program Files\MetaTrader 5\terminal64.exe" --host 0.0.0.0 --port 8000

Abra seu navegador em http://localhost:8000/docs para ver a documentação da API
No Open WebUI:
- Vá para Configurações → Ferramentas
- Clique em Adicionar servidor de ferramentas
- Digite http://localhost:8000
- Salve
Agora você pode usar as ferramentas de negociação em suas conversas do Open WebUI!

Opção C: Cotações em tempo real via WebSocket

Transmita dados de tick ao vivo (bid, ask, spread, volume) via WebSocket para painéis, bots ou monitoramento:

metatrader-quote-server --login YOUR_LOGIN --password YOUR_PASSWORD --server YOUR_SERVER

Conecte-se com qualquer cliente WebSocket:

websocat ws://localhost:8765

Você receberá uma mensagem connected seguida de atualizações contínuas de tick em JSON. Consulte Servidor de Cotações WebSocket para detalhes completos.

Opção D: Servidor MCP remoto (SSE)

Execute o servidor MCP em um VPS Windows (onde o MT5 está instalado) e conecte-se remotamente a partir do Claude Desktop ou Claude Code.

No servidor (no VPS Windows):

metatrader-mcp-server --login YOUR_LOGIN --password YOUR_PASSWORD --server YOUR_SERVER

Isso inicia o servidor SSE em 0.0.0.0:8080 por padrão. Personalize com --host e --port:

metatrader-mcp-server --login YOUR_LOGIN --password YOUR_PASSWORD --server YOUR_SERVER --host 127.0.0.1 --port 9000

No cliente (configuração do Claude Desktop na sua máquina local):

{
  "mcpServers": {
    "metatrader": {
      "url": "http://VPS_IP:8080/sse"
    }
  }
}

Substitua VPS_IP pelo endereço IP do seu servidor.

Aviso de segurança: O protocolo MCP não inclui autenticação. Ao expor o servidor SSE em uma rede, use um firewall para restringir o acesso por IP, ou coloque-o atrás de um proxy reverso com autenticação, ou use um túnel SSH.

🤖 Habilidade do Assistente de Negociação (Claude Code / Claude Desktop)

Uma habilidade pré-construída de Assistente de Terminal de Negociação está incluída no diretório claude-skill/. Ela fornece ao Claude conhecimento estruturado sobre todas as 32 ferramentas de negociação, formatação de saída e conhecimento especializado do MetaTrader 5.

Instalação para Claude Code

Opção 1: Symlink (recomendado)

Crie um symlink do diretório padrão de habilidades do Claude Code para claude-skill/:

cd metatrader-mcp-server
mkdir -p .claude
ln -s ../claude-skill .claude/skills

A habilidade será descoberta automaticamente e ficará disponível como /trading.

Opção 2: Copiar

Copie os arquivos da habilidade para o diretório de habilidades do Claude Code:

cd metatrader-mcp-server
mkdir -p .claude/skills
cp -r claude-skill/trading .claude/skills/trading

Instalação para Claude Desktop

Para Claude Desktop, copie a habilidade para o diretório global de habilidades do Claude:

# macOS
mkdir -p ~/Library/Application\ Support/Claude/skills
cp -r claude-skill/trading ~/Library/Application\ Support/Claude/skills/trading

# Windows
mkdir "%APPDATA%\Claude\skills"
xcopy /E claude-skill\trading "%APPDATA%\Claude\skills\trading\"

O que a habilidade faz

Execução direta: Executa negociações imediatamente quando solicitado, sem necessidade de confirmação extra
Fluxos de trabalho: Sabe como encadear ferramentas para operações complexas (ex.: colocar ordem de mercado e depois definir SL/TP)
Formatação: Apresenta dados de conta, posições, ordens e preços em tabelas limpas no estilo terminal
Conhecimento de domínio: Entende tipos de ordem MT5, períodos, formatos de símbolos e modos de preenchimento

Uso

Após a instalação, invoque com /trading ou simplesmente faça perguntas relacionadas a negociação de forma natural:

/trading
> Show me my account dashboard
> Buy 0.1 lots of EURUSD with SL at 1.0800
> Close all profitable positions
> Show me GBPUSD H4 candles

📡 Servidor de Cotações WebSocket

O Servidor de Cotações WebSocket transmite dados de tick em tempo real do MetaTrader 5 para qualquer cliente WebSocket. É ideal para painéis ao vivo, frontends de negociação algorítmica e monitoramento em tempo real.

Iniciando o servidor

metatrader-quote-server --login YOUR_LOGIN --password YOUR_PASSWORD --server YOUR_SERVER

O servidor inicia em ws://0.0.0.0:8765 por padrão.

Personalização

metatrader-quote-server \
  --login YOUR_LOGIN \
  --password YOUR_PASSWORD \
  --server YOUR_SERVER \
  --host 127.0.0.1 \
  --port 9000 \
  --symbols "EURUSD,GBPUSD,XAUUSD" \
  --poll-interval 200

Configuração

Flag	Variável de ambiente	Padrão	Descrição
`--host`	`QUOTE_HOST`	`0.0.0.0`	Host para vincular
`--port`	`QUOTE_PORT`	`8765`	Porta para vincular
`--symbols`	`QUOTE_SYMBOLS`	`XAUUSD,USOIL,GBPUSD,USDJPY,EURUSD,BTCUSD`	Símbolos separados por vírgula para transmitir
`--poll-interval`	`QUOTE_POLL_INTERVAL_MS`	`100`	Intervalo de sondagem de ticks em milissegundos

As flags de CLI têm precedência sobre as variáveis de ambiente, que têm precedência sobre os padrões.

Formato da mensagem

Ao conectar — o servidor envia uma mensagem connected com a lista de símbolos, seguida de quaisquer ticks em cache:

{"type": "connected", "symbols": ["XAUUSD", "EURUSD", "GBPUSD"], "poll_interval_ms": 100}

Atualizações de tick — enviadas sempre que bid, ask ou volume mudam:

{"type": "tick", "symbol": "XAUUSD", "bid": 2345.67, "ask": 2345.89, "spread": 0.22, "volume": 1234, "time": "2026-03-14T10:30:45+00:00"}

Erros — enviados se um símbolo não puder ser obtido:

{"type": "error", "symbol": "INVALID", "message": "Symbol not found or data unavailable"}

Exemplo: Conectando com Python

import asyncio
import json
from websockets.asyncio.client import connect

async def main():
    async with connect("ws://localhost:8765") as ws:
        async for message in ws:
            tick = json.loads(message)
            if tick["type"] == "tick":
                print(f"{tick['symbol']}: {tick['bid']}/{tick['ask']} (spread: {tick['spread']})")

asyncio.run(main())

Notas de design

Detecção de mudanças: Só transmite quando bid, ask ou volume realmente mudam, reduzindo tráfego desnecessário.
Participantes tardios: Novos clientes recebem ticks em cache imediatamente ao conectar, para não precisarem esperar pela próxima mudança.
Segurança de thread do MT5: Todas as chamadas do SDK do MT5 são serializadas através de um executor de thread única para evitar problemas de acesso concorrente.
Múltiplos clientes: Qualquer número de clientes WebSocket pode se conectar simultaneamente.

💡 Exemplos de uso

Com Claude Desktop

Após a configuração, você pode conversar naturalmente:

Verifique sua conta:

Você: "Mostre minhas informações da conta"

Claude: Retorna saldo, patrimônio, margem, alavancagem, etc.

Obtenha dados de mercado:

Você: "Qual é o preço atual do EUR/USD?"

Claude: Mostra bid, ask e spread

Faça uma negociação:

Você: "Compre 0,01 lotes de GBP/USD com stop loss em 1,2500 e take profit em 1,2700"

Claude: Executa a negociação e confirma

Gerencie posições:

Você: "Feche todas as minhas posições perdedoras"

Claude: Fecha as posições e relata os resultados

Analise o histórico:

Você: "Mostre todas as minhas negociações da semana passada para EUR/USD"

Claude: Retorna o histórico de negociações como uma tabela

Com API HTTP

# Get account info
curl http://localhost:8000/api/v1/account/info

# Get current price
curl "http://localhost:8000/api/v1/market/price?symbol_name=EURUSD"

# Place a market order
curl -X POST http://localhost:8000/api/v1/order/market \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "EURUSD",
    "volume": 0.01,
    "type": "BUY",
    "stop_loss": 1.0990,
    "take_profit": 1.1010
  }'

# Get all open positions
curl http://localhost:8000/api/v1/positions

# Close a specific position
curl -X DELETE http://localhost:8000/api/v1/positions/12345

Como biblioteca Python

from metatrader_client import MT5Client

# Connect to MT5
config = {
    "login": 12345678,
    "password": "your_password",
    "server": "MetaQuotes-Demo"
}
client = MT5Client(config)
client.connect()

# Get account statistics
stats = client.account.get_trade_statistics()
print(f"Balance: ${stats['balance']}")
print(f"Equity: ${stats['equity']}")

# Get current price
price = client.market.get_symbol_price("EURUSD")
print(f"EUR/USD Bid: {price['bid']}, Ask: {price['ask']}")

# Place a market order
result = client.order.place_market_order(
    type="BUY",
    symbol="EURUSD",
    volume=0.01,
    stop_loss=1.0990,
    take_profit=1.1010
)
print(result['message'])

# Close all positions
client.order.close_all_positions()

# Disconnect
client.disconnect()

📚 Operações disponíveis

Gerenciamento de conta

get_account_info - Obtenha saldo, patrimônio, lucro, nível de margem, alavancagem, moeda

Dados de mercado

get_symbols - Liste todos os símbolos de negociação disponíveis
get_symbol_price - Obtenha o preço atual de bid/ask para um símbolo
get_candles_latest - Obtenha candles de preço recentes (dados OHLCV)
get_candles_by_date - Obtenha candles históricos para um intervalo de datas
get_symbol_info - Obtenha informações detalhadas do símbolo

Execução de ordens

place_market_order - Execute ordens instantâneas de COMPRA/VENDA
place_pending_order - Coloque ordens limit/stop para execução futura
modify_position - Atualize stop loss ou take profit
modify_pending_order - Modifique parâmetros de ordens pendentes

Gerenciamento de posições

get_all_positions - Veja todas as posições abertas
get_positions_by_symbol - Filtre posições por par de negociação
get_positions_by_id - Obtenha detalhes de uma posição específica
close_position - Feche uma posição específica
close_all_positions - Feche todas as posições abertas
close_all_positions_by_symbol - Feche todas as posições de um símbolo
close_all_profitable_positions - Feche apenas negociações vencedoras
close_all_losing_positions - Feche apenas negociações perdedoras

Ordens pendentes

get_all_pending_orders - Liste todas as ordens pendentes
get_pending_orders_by_symbol - Filtre ordens pendentes por símbolo
cancel_pending_order - Cancele uma ordem pendente específica
cancel_all_pending_orders - Cancele todas as ordens pendentes
cancel_pending_orders_by_symbol - Cancele ordens pendentes de um símbolo

Histórico de negociações

get_deals - Obtenha negociações concluídas históricas
get_orders - Obtenha registros históricos de ordens

🔧 Configuração avançada

Usando variáveis de ambiente

Em vez de colocar credenciais na linha de comando, crie um arquivo .env:

LOGIN=12345678
PASSWORD=your_password
SERVER=MetaQuotes-Demo

# Optional: Specify custom MT5 terminal path (auto-detected if not provided)
# MT5_PATH=C:\Program Files\MetaTrader 5\terminal64.exe

Em seguida, inicie o servidor sem argumentos:

metatrader-http-server

O servidor carregará automaticamente as credenciais do arquivo .env.

Configuração de transporte MCP

O servidor MCP suporta múltiplos modos de transporte:

Flag	Env Var	Default	Descrição
`--transport`	`MCP_TRANSPORT`	`sse`	Tipo de transporte: `sse`, `stdio`, `streamable-http`
`--host`	`MCP_HOST`	`0.0.0.0`	Host para vinculação (somente SSE/HTTP)
`--port`	`MCP_PORT`	`8080`	Porta para vinculação (somente SSE/HTTP)

As flags de CLI têm precedência sobre as variáveis de ambiente, que têm precedência sobre os padrões.

Porta e Host Personalizados (API HTTP)

metatrader-http-server --host 127.0.0.1 --port 9000

Parâmetros de Conexão

O cliente MT5 suporta configuração adicional:

config = {
    "login": 12345678,
    "password": "your_password",
    "server": "MetaQuotes-Demo",
    "path": None,               # Path to MT5 terminal executable (default: auto-detect)
    "timeout": 60000,           # Connection timeout in milliseconds (default: 60000)
    "portable": False,          # Use portable mode (default: False)
    "max_retries": 3,           # Maximum connection retry attempts (default: 3)
    "backoff_factor": 1.5,      # Delay multiplier between retries (default: 1.5)
    "cooldown_time": 2.0,       # Seconds to wait between connections (default: 2.0)
    "debug": True               # Enable debug logging (default: False)
}

Opções de Configuração:

login (int, obrigatório): Seu número de login da conta MT5
password (str, obrigatório): Sua senha da conta MT5
server (str, obrigatório): Nome do servidor MT5 (ex.: "MetaQuotes-Demo")
path (str, opcional): Caminho completo para o executável do terminal MT5. Se não for especificado, o cliente procurará automaticamente nos diretórios de instalação padrão
timeout (int, opcional): Tempo limite de conexão em milissegundos. Padrão: 60000 (60 segundos)
portable (bool, opcional): Ativar modo portátil para o terminal MT5. Padrão: False
max_retries (int, opcional): Número máximo de tentativas de reconexão. Padrão: 3
backoff_factor (float, opcional): Fator de backoff exponencial para atrasos de nova tentativa. Padrão: 1.5
cooldown_time (float, opcional): Tempo mínimo em segundos entre tentativas de conexão. Padrão: 2.0
debug (bool, opcional): Ativar registro de depuração detalhado para solução de problemas. Padrão: False

🗺️ Roadmap

Recurso	Status
MetaTrader 5 Connection	✅ Concluído
Python Client Library	✅ Concluído
MCP Server	✅ Concluído
Claude Desktop Integration	✅ Concluído
HTTP/REST API Server	✅ Concluído
Open WebUI Integration	✅ Concluído
OpenAPI Documentation	✅ Concluído
PyPI Package	✅ Publicado
SSE Transport Support	✅ Concluído
Google ADK Integration	🚧 Em andamento
WebSocket Quote Server	✅ Concluído
Docker Container	📋 Planejado

🛠️ Desenvolvimento

Configurando o Ambiente de Desenvolvimento

# Clone the repository
git clone https://github.com/ariadng/metatrader-mcp-server.git
cd metatrader-mcp-server

# Install in development mode
pip install -e .

# Install development dependencies
pip install pytest python-dotenv

# Run tests
pytest tests/

Estrutura do Projeto

metatrader-mcp-server/
├── src/
│   ├── metatrader_client/      # Core MT5 client library
│   │   ├── account/            # Account operations
│   │   ├── connection/         # Connection management
│   │   ├── history/            # Historical data
│   │   ├── market/             # Market data
│   │   ├── order/              # Order execution
│   │   └── types/              # Type definitions
│   ├── metatrader_mcp/         # MCP server implementation
│   ├── metatrader_openapi/     # HTTP/REST API server
│   └── metatrader_quote/       # WebSocket quote streamer
├── tests/                      # Test suite
├── docs/                       # Documentation
└── pyproject.toml             # Project configuration

🤝 Contribuindo

Contribuições são bem-vindas! Veja como você pode ajudar:

Relatar Bugs - Abra uma issue
Sugerir Recursos - Compartilhe suas ideias nas issues
Enviar Pull Requests - Corrija bugs ou adicione recursos
Melhorar a Documentação - Ajude a tornar a documentação mais clara
Compartilhar Exemplos - Mostre como você está usando

Diretrizes de Contribuição

Faça um fork do repositório
Crie um branch de recurso (git checkout -b feature/amazing-feature)
Faça suas alterações
Escreva ou atualize testes
Garanta que os testes passem (pytest)
Faça commit das suas alterações (git commit -m 'Add amazing feature')
Envie para o branch (git push origin feature/amazing-feature)
Abra um Pull Request

📖 Documentação

Documentação do Desenvolvedor - Documentação técnica detalhada
Referência da API - Documentação completa da API
Exemplos - Exemplos de código e tutoriais
Roadmap - Cronograma de desenvolvimento de recursos

🆘 Obtendo Ajuda

Issues: Issues do GitHub
Discussões: Discussões do GitHub
LinkedIn: Conecte-se comigo

Problemas Comuns

"Falha na conexão"

Certifique-se de que o terminal MT5 está em execução
Verifique se a negociação algorítmica está habilitada
Verifique se suas credenciais de login estão corretas

"Módulo não encontrado"

Certifique-se de ter instalado o pacote: pip install metatrader-mcp-server
Verifique se sua versão do Python é 3.10 ou superior

"Falha na execução da ordem"

Verifique se o símbolo existe na sua corretora
Verifique se o mercado está aberto
Certifique-se de ter margem suficiente

📝 Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

🙏 Agradecimentos

Construído com FastMCP para suporte ao protocolo MCP
Usa o pacote Python MetaTrader5
Desenvolvido com FastAPI para a API REST

📊 Estatísticas do Projeto

Versão: 0.5.1
Python: 3.10+
Licença: MIT
Status: Desenvolvimento Ativo

Feito com ❤️ por Aria Dhanang

⭐ Dê uma estrela neste repositório se você o achar útil!

PyPI • GitHub • Issues