trading-platform-mcp-mt4-connector-v2/README.md

MCP MT4 Connector

Version: 0.1.0 Date: 2026-01-04 System: Trading Platform + NEXUS v3.4 + SIMCO

---

Description

MCP Server that exposes MetaTrader 4 (MT4) trading capabilities as tools for AI agents. This service enables AI agents to:

• Query account information
• Monitor open positions
• Execute trades (BUY/SELL)
• Manage positions (modify SL/TP, close)
• Get real-time price quotes

---

Installation

# Navigate to the project
cd /home/isem/workspace-v1/projects/trading-platform/apps/mcp-mt4-connector

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your MT4 Gateway credentials

---

Configuration

Environment Variables

Variable	Description	Default
PORT	MCP Server port	3605
MT4_GATEWAY_HOST	MT4 Gateway hostname	localhost
MT4_GATEWAY_PORT	MT4 Gateway port	8081
MT4_GATEWAY_AUTH_TOKEN	Authentication token	secret
REQUEST_TIMEOUT	Request timeout (ms)	10000
LOG_LEVEL	Logging level	info

Example .env

PORT=3605
MT4_GATEWAY_HOST=localhost
MT4_GATEWAY_PORT=8081
MT4_GATEWAY_AUTH_TOKEN=your-secure-token
REQUEST_TIMEOUT=10000
LOG_LEVEL=info

---

Usage

Start Server

# Development (with hot reload)
npm run dev

# Production
npm run build
npm start

Health Check

curl http://localhost:3605/health

List Available Tools

curl http://localhost:3605/tools

Execute a Tool

# Get account info
curl -X POST http://localhost:3605/tools/mt4_get_account \
  -H "Content-Type: application/json" \
  -d '{"parameters": {}}'

# Get price quote
curl -X POST http://localhost:3605/tools/mt4_get_quote \
  -H "Content-Type: application/json" \
  -d '{"parameters": {"symbol": "XAUUSD"}}'

# Execute trade
curl -X POST http://localhost:3605/tools/mt4_execute_trade \
  -H "Content-Type: application/json" \
  -d '{"parameters": {"symbol": "XAUUSD", "action": "buy", "lots": 0.1}}'

---

MCP Tools Available

Tool	Description	Risk
mt4_get_account	Get account balance, equity, margin	Low
mt4_get_positions	List open positions	Low
mt4_get_quote	Get current bid/ask price	Low
mt4_execute_trade	Execute BUY/SELL order	HIGH
mt4_close_position	Close a position	HIGH
mt4_modify_position	Modify SL/TP	Medium

---

Project Structure

mcp-mt4-connector/
├── README.md                 # This file
├── package.json              # Dependencies
├── tsconfig.json             # TypeScript configuration
├── .env.example              # Environment template
├── .gitignore                # Git ignore rules
├── docs/
│   ├── ARCHITECTURE.md       # Architecture documentation
│   └── MCP-TOOLS-SPEC.md     # Detailed tool specifications
└── src/
    ├── index.ts              # Server entry point
    ├── tools/
    │   ├── index.ts          # Tool exports
    │   ├── account.ts        # mt4_get_account
    │   ├── positions.ts      # mt4_get_positions, mt4_close_position
    │   ├── trading.ts        # mt4_execute_trade, mt4_modify_position
    │   └── quotes.ts         # mt4_get_quote
    └── services/
        └── mt4-client.ts     # MT4 Gateway HTTP client

---

Development

Build

npm run build

Type Check

npm run typecheck

Lint

npm run lint
npm run lint:fix

Test

npm run test
npm run test:coverage

---

Integration with Claude

MCP Configuration

Add to your Claude/MCP configuration:

{
  "mcpServers": {
    "mt4": {
      "url": "http://localhost:3605",
      "transport": "http"
    }
  }
}

Example Agent Prompts

"Check my MT4 account balance"
→ Uses mt4_get_account

"What's the current gold price?"
→ Uses mt4_get_quote({ symbol: "XAUUSD" })

"Buy 0.1 lots of XAUUSD with stop loss at 2640"
→ Uses mt4_execute_trade({ symbol: "XAUUSD", action: "buy", lots: 0.1, stopLoss: 2640 })

"Close my profitable gold positions"
→ Uses mt4_get_positions({ symbol: "XAUUSD" }) + mt4_close_position for each

---

Dependencies

Runtime

• express - HTTP server
• axios - HTTP client
• zod - Input validation
• dotenv - Environment configuration
• @modelcontextprotocol/sdk - MCP protocol

Development

• typescript - Type safety
• ts-node-dev - Development server
• jest - Testing framework
• eslint - Code linting

---

Prerequisites

1. MT4 Gateway running on configured host:port
2. MT4 Terminal connected with EA Bridge active
3. Node.js >= 18.0.0

---

Troubleshooting

Cannot connect to MT4 Gateway

# Check if mt4-gateway is running
curl http://localhost:8081/status

# Verify environment variables
cat .env | grep MT4

Tool execution fails

# Check health endpoint for dependency status
curl http://localhost:3605/health

# Check server logs
npm run dev  # Logs will show in console

Invalid parameters error

# Verify tool schema
curl http://localhost:3605/tools/mt4_execute_trade

# Check parameter names match schema

---

References

• MCP Protocol
• MT4 Gateway: apps/mt4-gateway/
• SIMCO-MCP: orchestration/directivas/simco/SIMCO-MCP.md
• Architecture: docs/ARCHITECTURE.md
• Tool Specs: docs/MCP-TOOLS-SPEC.md

---

Maintained by: @PERFIL_MCP_DEVELOPER Project: Trading Platform