MetaTrader MCP Server

Un servidor MCP basado en Python que permite a los LLMs de IA ejecutar operaciones en la plataforma MetaTrader 5.

GitHub

795

Prueba este MCPPatrocinado

Documentación

MetaTrader MCP Server

Permite que los asistentes de IA operen por ti usando lenguaje natural

MetaTrader MCP Server

📑 Tabla de Contenidos

¿Qué es esto?
Características
¿Para quién es?
Aviso Legal Importante
Requisitos Previos
Inicio Rápido
Habilidad del Asistente de Trading
Ejemplos de Uso
Operaciones Disponibles
Servidor de Cotizaciones WebSocket
Configuración Avanzada
Hoja de Ruta
Desarrollo
Contribuciones
Documentación
Obtener Ayuda
Licencia

🌟 ¿Qué es esto?

MetaTrader MCP Server es un puente que conecta asistentes de IA (como Claude, ChatGPT) con la plataforma de trading MetaTrader 5. En lugar de hacer clic en botones, simplemente puedes decirle a tu asistente de IA qué hacer:

"Muéstrame mi saldo de cuenta" "Compra 0.01 lotes de EUR/USD" "Cierra todas las posiciones rentables"

La IA entiende tu solicitud y la ejecuta en MetaTrader 5 automáticamente.

Cómo Funciona

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

✨ Características

🗣️ Trading con Lenguaje Natural - Habla con la IA en lenguaje sencillo para ejecutar operaciones
🤖 Soporte Multi-IA - Funciona con Claude Desktop, ChatGPT (vía Open WebUI) y más
📊 Acceso Completo al Mercado - Obtén precios en tiempo real, datos históricos e información de símbolos
💼 Control Total de la Cuenta - Consulta saldo, capital, margen y estadísticas de trading
⚡ Gestión de Órdenes - Coloca, modifica y cierra órdenes con comandos simples
🔒 Seguro - Todas las credenciales permanecen en tu máquina
🌐 Interfaces Flexibles - Úsalo como servidor MCP, API REST o flujo WebSocket
📖 Bien Documentado - Guías y ejemplos completos

🎯 ¿Para quién es?

Traders que quieren automatizar sus operaciones usando IA
Desarrolladores que crean bots de trading o herramientas de análisis
Analistas que necesitan acceso rápido a datos de mercado
Cualquiera interesado en combinar IA con mercados financieros

⚠️ Aviso Legal Importante

Por favor, lee esto con atención:

Operar con instrumentos financieros implica un riesgo significativo de pérdida. Este software se proporciona tal cual, y los desarrolladores no aceptan ninguna responsabilidad por pérdidas, ganancias o consecuencias derivadas del uso de este software.

Al usar este software, reconoces que:

Entiendes los riesgos del trading financiero
Eres responsable de todas las operaciones ejecutadas a través de este sistema
No responsabilizarás a los desarrolladores por ningún resultado
Estás usando este software bajo tu propio riesgo

Esto no es asesoramiento financiero. Opera siempre de manera responsable.

📋 Requisitos Previos

Antes de comenzar, asegúrate de tener:

Python 3.10 o superior - Descargar aquí
Terminal MetaTrader 5 - Descargar aquí
Cuenta de Trading MT5 - Credenciales de cuenta demo o real
- Número de inicio de sesión
- Contraseña
- Nombre del servidor (por ejemplo, "MetaQuotes-Demo")

🚀 Inicio Rápido

Paso 1: Instala el Paquete

Abre tu terminal o símbolo del sistema y ejecuta:

pip install metatrader-mcp-server

Paso 2: Habilita el Trading Algorítmico

Abre MetaTrader 5
Ve a Tools → Options
Haz clic en la pestaña Expert Advisors
Marca la casilla para Allow algorithmic trading
Haz clic en OK

Paso 3: Elige tu Interfaz

Elige una según cómo quieras usarlo:

Opción A: Usar con Claude Desktop (STDIO Local)

Encuentra tu archivo de configuración de Claude Desktop:
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
Abre el archivo y añade esta configuración:

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

Opcional: Especificar Ruta Personalizada del Terminal MT5

Si tu terminal MT5 está instalado en una ubicación no estándar, añade el 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"
      ]
    }
  }
}

Reemplaza YOUR_MT5_LOGIN, YOUR_MT5_PASSWORD y YOUR_MT5_SERVER con tus credenciales reales
Reinicia Claude Desktop
¡Empieza a chatear! Prueba: "¿Cuál es mi saldo de cuenta?"

Opción B: Usar con Open WebUI (Para ChatGPT y otros LLMs)

Inicia el servidor HTTP:

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

Opcional: Especificar Ruta Personalizada del Terminal MT5

Si tu terminal MT5 está instalado en una ubicación no estándar, añade el 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

Abre tu navegador en http://localhost:8000/docs para ver la documentación de la API
En Open WebUI:
- Ve a Configuración → Herramientas
- Haz clic en Añadir Servidor de Herramientas
- Introduce http://localhost:8000
- Guarda
¡Ahora puedes usar las herramientas de trading en tus chats de Open WebUI!

Opción C: Cotizaciones en Tiempo Real vía WebSocket

Transmite datos de tick en vivo (bid, ask, spread, volumen) a través de WebSocket para paneles, bots o monitoreo:

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

Conéctate con cualquier cliente WebSocket:

websocat ws://localhost:8765

Recibirás un mensaje connected seguido de actualizaciones continuas de ticks en formato JSON. Consulta Servidor de Cotizaciones WebSocket para más detalles.

Opción D: Servidor MCP Remoto (SSE)

Ejecuta el servidor MCP en un VPS con Windows (donde esté instalado MT5) y conéctate remotamente desde Claude Desktop o Claude Code.

Lado del servidor (en el VPS con Windows):

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

Esto inicia el servidor SSE en 0.0.0.0:8080 por defecto. Personaliza con --host y --port:

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

Lado del cliente (configuración de Claude Desktop en tu máquina local):

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

Reemplaza VPS_IP con la dirección IP de tu servidor.

Advertencia de Seguridad: El protocolo MCP no incluye autenticación. Al exponer el servidor SSE a través de una red, usa un firewall para restringir el acceso por IP, o colócalo detrás de un proxy inverso con autenticación, o usa un túnel SSH.

🤖 Habilidad del Asistente de Trading (Claude Code / Claude Desktop)

Se incluye una habilidad preconstruida de Asistente de Terminal de Trading en el directorio claude-skill/. Proporciona a Claude conocimiento estructurado sobre las 32 herramientas de trading, formato de salida y experiencia en el dominio de MetaTrader 5.

Instalación para Claude Code

Opción 1: Enlace simbólico (recomendado)

Crea un enlace simbólico desde el directorio estándar de habilidades de Claude Code a claude-skill/:

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

La habilidad se descubrirá automáticamente y estará disponible como /trading.

Opción 2: Copiar

Copia los archivos de la habilidad al directorio de habilidades de Claude Code:

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

Instalación para Claude Desktop

Para Claude Desktop, copia la habilidad al directorio global de habilidades de 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\"

Qué Hace la Habilidad

Ejecución Directa: Ejecuta operaciones inmediatamente cuando se solicitan, sin necesidad de confirmación adicional
Flujos de Trabajo: Sabe cómo encadenar herramientas para operaciones complejas (por ejemplo, colocar una orden de mercado y luego establecer SL/TP)
Formato: Presenta datos de cuenta, posiciones, órdenes y precios en tablas limpias estilo terminal
Conocimiento del Dominio: Entiende los tipos de órdenes de MT5, marcos temporales, formatos de símbolos y modos de llenado

Uso

Una vez instalada, invócala con /trading o simplemente haz preguntas relacionadas con trading 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 Cotizaciones WebSocket

El Servidor de Cotizaciones WebSocket transmite datos de tick en tiempo real desde MetaTrader 5 a cualquier cliente WebSocket. Es ideal para paneles en vivo, frontends de trading algorítmico y monitoreo en tiempo real.

Iniciar el Servidor

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

El servidor se inicia en ws://0.0.0.0:8765 por defecto.

Personalización

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

Configuración

Indicador	Variable de Entorno	Valor por Defecto	Descripción
`--host`	`QUOTE_HOST`	`0.0.0.0`	Host al que vincularse
`--port`	`QUOTE_PORT`	`8765`	Puerto al que vincularse
`--symbols`	`QUOTE_SYMBOLS`	`XAUUSD,USOIL,GBPUSD,USDJPY,EURUSD,BTCUSD`	Símbolos a transmitir separados por comas
`--poll-interval`	`QUOTE_POLL_INTERVAL_MS`	`100`	Intervalo de sondeo de ticks en milisegundos

Los indicadores de CLI tienen prioridad sobre las variables de entorno, que a su vez tienen prioridad sobre los valores por defecto.

Formato de Mensaje

Al conectar — el servidor envía un mensaje connected con la lista de símbolos, seguido de cualquier tick almacenado en caché:

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

Actualizaciones de ticks — se envían cuando cambia el bid, ask o volumen:

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

Errores — se envían si no se puede obtener un símbolo:

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

Ejemplo: Conexión con 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 Diseño

Detección de cambios: Solo transmite cuando el bid, ask o volumen cambian realmente, reduciendo tráfico innecesario.
Recién llegados: Los nuevos clientes reciben ticks almacenados en caché inmediatamente al conectar, para que no tengan que esperar al siguiente cambio.
Seguridad de hilos en MT5: Todas las llamadas al SDK de MT5 se serializan a través de un ejecutor de un solo hilo para evitar problemas de acceso concurrente.
Múltiples clientes: Cualquier número de clientes WebSocket puede conectarse simultáneamente.

💡 Ejemplos de Uso

Con Claude Desktop

Una vez configurado, puedes chatear de forma natural:

Consulta tu Cuenta:

Tú: "Muéstrame mi información de cuenta"

Claude: Devuelve saldo, capital, margen, apalancamiento, etc.

Obtén Datos de Mercado:

Tú: "¿Cuál es el precio actual de EUR/USD?"

Claude: Muestra bid, ask y spread

Coloca una Operación:

Tú: "Compra 0.01 lotes de GBP/USD con stop loss en 1.2500 y take profit en 1.2700"

Claude: Ejecuta la operación y confirma

Gestiona Posiciones:

Tú: "Cierra todas mis posiciones perdedoras"

Claude: Cierra las posiciones e informa los resultados

Analiza el Historial:

Tú: "Muéstrame todas mis operaciones de la semana pasada para EUR/USD"

Claude: Devuelve el historial de operaciones como una tabla

Con 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 de 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()

📚 Operaciones Disponibles

Gestión de Cuenta

get_account_info - Obtén saldo, capital, beneficio, nivel de margen, apalancamiento, moneda

Datos de Mercado

get_symbols - Lista todos los símbolos de trading disponibles
get_symbol_price - Obtén el precio bid/ask actual de un símbolo
get_candles_latest - Obtén velas de precio recientes (datos OHLCV)
get_candles_by_date - Obtén velas históricas para un rango de fechas
get_symbol_info - Obtén información detallada del símbolo

Ejecución de Órdenes

place_market_order - Ejecuta órdenes instantáneas de COMPRA/VENTA
place_pending_order - Coloca órdenes limit/stop para ejecución futura
modify_position - Actualiza stop loss o take profit
modify_pending_order - Modifica parámetros de órdenes pendientes

Gestión de Posiciones

get_all_positions - Ver todas las posiciones abiertas
get_positions_by_symbol - Filtra posiciones por par de trading
get_positions_by_id - Obtén detalles de una posición específica
close_position - Cierra una posición específica
close_all_positions - Cierra todas las posiciones abiertas
close_all_positions_by_symbol - Cierra todas las posiciones de un símbolo
close_all_profitable_positions - Cierra solo las operaciones ganadoras
close_all_losing_positions - Cierra solo las operaciones perdedoras

Órdenes Pendientes

get_all_pending_orders - Lista todas las órdenes pendientes
get_pending_orders_by_symbol - Filtra órdenes pendientes por símbolo
cancel_pending_order - Cancela una orden pendiente específica
cancel_all_pending_orders - Cancela todas las órdenes pendientes
cancel_pending_orders_by_symbol - Cancela órdenes pendientes de un símbolo

Historial de Trading

get_deals - Obtén operaciones completadas históricas
get_orders - Obtén registros de órdenes históricas

🔧 Configuración Avanzada

Usar Variables de Entorno

En lugar de poner credenciales en la línea de comandos, crea un archivo .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

Luego inicia el servidor sin argumentos:

metatrader-http-server

El servidor cargará automáticamente las credenciales del archivo .env.

Configuración de Transporte MCP

El servidor MCP soporta múltiples modos de transporte:

Flag	Env Var	Default	Description
`--transport`	`MCP_TRANSPORT`	`sse`	Tipo de transporte: `sse`, `stdio`, `streamable-http`
`--host`	`MCP_HOST`	`0.0.0.0`	Host al que vincularse (solo SSE/HTTP)
`--port`	`MCP_PORT`	`8080`	Puerto al que vincularse (solo SSE/HTTP)

Los flags de CLI tienen prioridad sobre las variables de entorno, que a su vez tienen prioridad sobre los valores predeterminados.

Puerto y Host Personalizados (API HTTP)

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

Parámetros de Conexión

El cliente MT5 admite configuración 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)
}

Opciones de Configuración:

login (int, obligatorio): Tu número de inicio de sesión de la cuenta MT5
password (str, obligatorio): La contraseña de tu cuenta MT5
server (str, obligatorio): Nombre del servidor MT5 (p. ej., "MetaQuotes-Demo")
path (str, opcional): Ruta completa al ejecutable del terminal MT5. Si no se especifica, el cliente buscará automáticamente en los directorios de instalación estándar
timeout (int, opcional): Tiempo de espera de conexión en milisegundos. Valor predeterminado: 60000 (60 segundos)
portable (bool, opcional): Habilita el modo portátil para el terminal MT5. Valor predeterminado: False
max_retries (int, opcional): Número máximo de intentos de reconexión. Valor predeterminado: 3
backoff_factor (float, opcional): Factor de retroceso exponencial para los retrasos de reintento. Valor predeterminado: 1.5
cooldown_time (float, opcional): Tiempo mínimo en segundos entre intentos de conexión. Valor predeterminado: 2.0
debug (bool, opcional): Habilita el registro de depuración detallado para la resolución de problemas. Valor predeterminado: False

🗺️ Hoja de Ruta

Característica	Estado
Conexión MetaTrader 5	✅ Completa
Biblioteca de Cliente Python	✅ Completa
Servidor MCP	✅ Completo
Integración con Claude Desktop	✅ Completa
Servidor de API HTTP/REST	✅ Completo
Integración con Open WebUI	✅ Completa
Documentación OpenAPI	✅ Completa
Paquete PyPI	✅ Publicado
Soporte de Transporte SSE	✅ Completo
Integración con Google ADK	🚧 En Progreso
Servidor de Cotizaciones WebSocket	✅ Completo
Contenedor Docker	📋 Planificado

🛠️ Desarrollo

Configuración del Entorno de Desarrollo

# 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/

Estructura del Proyecto

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

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Así es como puedes ayudar:

Reportar Errores - Abrir un issue
Sugerir Características - Comparte tus ideas en los issues
Enviar Pull Requests - Corrige errores o añade características
Mejorar la Documentación - Ayuda a que los documentos sean más claros
Compartir Ejemplos - Muestra cómo lo estás usando

Pautas de Contribución

Haz un fork del repositorio
Crea una rama de características (git checkout -b feature/amazing-feature)
Realiza tus cambios
Escribe o actualiza las pruebas
Asegúrate de que las pruebas pasen (pytest)
Confirma tus cambios (git commit -m 'Add amazing feature')
Sube a la rama (git push origin feature/amazing-feature)
Abre un Pull Request

📖 Documentación

Documentación para Desarrolladores - Documentación técnica detallada
Referencia de API - Documentación completa de la API
Ejemplos - Ejemplos de código y tutoriales
Hoja de Ruta - Cronograma de desarrollo de características

🆘 Obtener Ayuda

Issues: Issues de GitHub
Discusiones: Discusiones de GitHub
LinkedIn: Conéctate conmigo

Problemas Comunes

"Conexión fallida"

Asegúrate de que el terminal MT5 esté en ejecución
Verifica que el comercio algorítmico esté habilitado
Confirma que tus credenciales de inicio de sesión sean correctas

"Módulo no encontrado"

Asegúrate de haber instalado el paquete: pip install metatrader-mcp-server
Verifica que tu versión de Python sea 3.10 o superior

"Ejecución de orden fallida"

Verifica que el símbolo exista en tu bróker
Comprueba que el mercado esté abierto
Asegúrate de tener suficiente margen

📝 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

🙏 Agradecimientos

Construido con FastMCP para soporte del protocolo MCP
Utiliza el paquete Python MetaTrader5
Impulsado por FastAPI para la API REST

📊 Estadísticas del Proyecto

Versión: 0.5.1
Python: 3.10+
Licencia: MIT
Estado: Desarrollo Activo

Hecho con ❤️ por Aria Dhanang

⭐ ¡Dale una estrella a este repositorio si te resulta útil!

PyPI • GitHub • Issues