429 lines
9.5 KiB
Markdown
429 lines
9.5 KiB
Markdown
# MCP MT4 Connector - Tools Specification
|
|
|
|
**Version:** 0.1.0
|
|
**Date:** 2026-01-04
|
|
**Total Tools:** 6
|
|
|
|
---
|
|
|
|
## Tool Overview
|
|
|
|
| Tool Name | Description | Risk Level |
|
|
|-----------|-------------|------------|
|
|
| `mt4_get_account` | Get account information | Low |
|
|
| `mt4_get_positions` | List open positions | Low |
|
|
| `mt4_get_quote` | Get current price quote | Low |
|
|
| `mt4_execute_trade` | Execute market order | HIGH |
|
|
| `mt4_close_position` | Close a position | HIGH |
|
|
| `mt4_modify_position` | Modify SL/TP | Medium |
|
|
|
|
---
|
|
|
|
## mt4_get_account
|
|
|
|
### Description
|
|
Retrieves comprehensive account information from the connected MT4 terminal including balance, equity, margin, leverage, and broker details.
|
|
|
|
### Parameters
|
|
| Name | Type | Required | Description |
|
|
|------|------|----------|-------------|
|
|
| - | - | - | No parameters required |
|
|
|
|
### Return Value
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"balance": 10000.00,
|
|
"equity": 10250.50,
|
|
"margin": 500.00,
|
|
"freeMargin": 9750.50,
|
|
"marginLevel": 2050.10,
|
|
"profit": 250.50,
|
|
"currency": "USD",
|
|
"leverage": 100,
|
|
"name": "Demo Account",
|
|
"server": "ICMarkets-Demo",
|
|
"company": "IC Markets"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Example Usage
|
|
```typescript
|
|
// Get account info
|
|
const result = await mt4_get_account({});
|
|
|
|
// Response content:
|
|
// MT4 Account Information
|
|
// =======================
|
|
// Account Name: Demo Account
|
|
// Server: ICMarkets-Demo
|
|
// Broker: IC Markets
|
|
// Leverage: 1:100
|
|
//
|
|
// Financial Summary
|
|
// -----------------
|
|
// Balance: 10000.00 USD
|
|
// Equity: 10250.50 USD
|
|
// Profit/Loss: +250.50 USD
|
|
```
|
|
|
|
### Errors
|
|
| Code | Message | Solution |
|
|
|------|---------|----------|
|
|
| - | MT4 terminal is not connected | Check MT4 Gateway connection |
|
|
|
|
---
|
|
|
|
## mt4_get_positions
|
|
|
|
### Description
|
|
Lists all currently open trading positions from the MT4 terminal. Can optionally filter by symbol.
|
|
|
|
### Parameters
|
|
| Name | Type | Required | Description |
|
|
|------|------|----------|-------------|
|
|
| `symbol` | string | No | Filter positions by symbol (e.g., XAUUSD) |
|
|
|
|
### Return Value
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"positions": [
|
|
{
|
|
"ticket": 123456,
|
|
"symbol": "XAUUSD",
|
|
"type": "buy",
|
|
"lots": 0.10,
|
|
"openPrice": 2650.50,
|
|
"currentPrice": 2655.00,
|
|
"stopLoss": 2640.00,
|
|
"takeProfit": 2680.00,
|
|
"profit": 45.00,
|
|
"swap": -1.20,
|
|
"openTime": "2026-01-04T10:30:00Z",
|
|
"magic": 12345,
|
|
"comment": "AI Signal"
|
|
}
|
|
],
|
|
"totalProfit": 45.00,
|
|
"count": 1
|
|
}
|
|
}
|
|
```
|
|
|
|
### Example Usage
|
|
```typescript
|
|
// Get all positions
|
|
const result = await mt4_get_positions({});
|
|
|
|
// Get only XAUUSD positions
|
|
const goldPositions = await mt4_get_positions({ symbol: "XAUUSD" });
|
|
```
|
|
|
|
### Errors
|
|
| Code | Message | Solution |
|
|
|------|---------|----------|
|
|
| - | MT4 terminal is not connected | Check MT4 Gateway connection |
|
|
|
|
---
|
|
|
|
## mt4_get_quote
|
|
|
|
### Description
|
|
Retrieves the current bid/ask prices for a trading symbol. Also calculates the spread in points/pips.
|
|
|
|
### Parameters
|
|
| Name | Type | Required | Description |
|
|
|------|------|----------|-------------|
|
|
| `symbol` | string | Yes | Trading symbol (e.g., XAUUSD, EURUSD) |
|
|
|
|
### Return Value
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"symbol": "XAUUSD",
|
|
"bid": 2650.50,
|
|
"ask": 2650.80,
|
|
"spread": 0.30,
|
|
"timestamp": "2026-01-04T12:00:00.000Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Example Usage
|
|
```typescript
|
|
// Get gold price
|
|
const quote = await mt4_get_quote({ symbol: "XAUUSD" });
|
|
|
|
// Response content:
|
|
// Price Quote: XAUUSD
|
|
// =========================
|
|
// Bid: 2650.50
|
|
// Ask: 2650.80
|
|
// Spread: 0.30 (3.0 pips)
|
|
// Time: 2026-01-04T12:00:00.000Z
|
|
```
|
|
|
|
### Errors
|
|
| Code | Message | Solution |
|
|
|------|---------|----------|
|
|
| - | No quote data available for {symbol} | Verify symbol is available on broker |
|
|
|
|
---
|
|
|
|
## mt4_execute_trade
|
|
|
|
### Description
|
|
Opens a new trading position with a market order. Supports BUY and SELL orders with optional stop loss and take profit levels.
|
|
|
|
### Parameters
|
|
| Name | Type | Required | Description |
|
|
|------|------|----------|-------------|
|
|
| `symbol` | string | Yes | Trading symbol (e.g., XAUUSD) |
|
|
| `action` | string | Yes | Trade direction: "buy" or "sell" |
|
|
| `lots` | number | Yes | Volume in lots (e.g., 0.01, 0.1, 1.0) |
|
|
| `stopLoss` | number | No | Stop loss price level |
|
|
| `takeProfit` | number | No | Take profit price level |
|
|
| `slippage` | number | No | Maximum slippage in points (default: 3) |
|
|
| `magic` | number | No | Magic number for EA identification (default: 12345) |
|
|
| `comment` | string | No | Order comment (max 31 chars) |
|
|
|
|
### Return Value
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"success": true,
|
|
"ticket": 123456,
|
|
"message": "Order placed successfully",
|
|
"symbol": "XAUUSD",
|
|
"action": "buy",
|
|
"lots": 0.1
|
|
}
|
|
}
|
|
```
|
|
|
|
### Example Usage
|
|
```typescript
|
|
// Simple buy order
|
|
const result = await mt4_execute_trade({
|
|
symbol: "XAUUSD",
|
|
action: "buy",
|
|
lots: 0.1
|
|
});
|
|
|
|
// Buy with risk management
|
|
const result = await mt4_execute_trade({
|
|
symbol: "XAUUSD",
|
|
action: "buy",
|
|
lots: 0.1,
|
|
stopLoss: 2640.00,
|
|
takeProfit: 2680.00,
|
|
comment: "AI Signal - Gold Long"
|
|
});
|
|
|
|
// Sell order
|
|
const result = await mt4_execute_trade({
|
|
symbol: "EURUSD",
|
|
action: "sell",
|
|
lots: 0.5,
|
|
stopLoss: 1.1050,
|
|
takeProfit: 1.0900
|
|
});
|
|
```
|
|
|
|
### Validation Rules
|
|
- For BUY orders: stopLoss must be below takeProfit
|
|
- For SELL orders: stopLoss must be above takeProfit
|
|
- Lots must be positive and reasonable (max 100)
|
|
|
|
### Errors
|
|
| Code | Message | Solution |
|
|
|------|---------|----------|
|
|
| - | For BUY orders, stop loss must be below take profit | Fix SL/TP levels |
|
|
| - | For SELL orders, stop loss must be above take profit | Fix SL/TP levels |
|
|
| - | Trade execution failed | Check margin, market hours |
|
|
|
|
---
|
|
|
|
## mt4_close_position
|
|
|
|
### Description
|
|
Closes an open position by ticket number. Can optionally close only a partial volume.
|
|
|
|
### Parameters
|
|
| Name | Type | Required | Description |
|
|
|------|------|----------|-------------|
|
|
| `ticket` | number | Yes | Position ticket number to close |
|
|
| `lots` | number | No | Partial volume to close (default: close all) |
|
|
| `slippage` | number | No | Maximum slippage in points (default: 3) |
|
|
|
|
### Return Value
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"success": true,
|
|
"ticket": 123456,
|
|
"message": "Position closed"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Example Usage
|
|
```typescript
|
|
// Close entire position
|
|
const result = await mt4_close_position({
|
|
ticket: 123456
|
|
});
|
|
|
|
// Close partial position (0.5 of 1.0 lots)
|
|
const result = await mt4_close_position({
|
|
ticket: 123456,
|
|
lots: 0.5
|
|
});
|
|
```
|
|
|
|
### Errors
|
|
| Code | Message | Solution |
|
|
|------|---------|----------|
|
|
| - | Position with ticket {x} not found | Verify ticket number |
|
|
| - | Requested lots exceeds position size | Reduce lots parameter |
|
|
|
|
---
|
|
|
|
## mt4_modify_position
|
|
|
|
### Description
|
|
Modifies the stop loss and/or take profit levels of an existing open position.
|
|
|
|
### Parameters
|
|
| Name | Type | Required | Description |
|
|
|------|------|----------|-------------|
|
|
| `ticket` | number | Yes | Position ticket number to modify |
|
|
| `stopLoss` | number | No | New stop loss price level |
|
|
| `takeProfit` | number | No | New take profit price level |
|
|
|
|
### Return Value
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"success": true,
|
|
"ticket": 123456,
|
|
"message": "Position modified successfully"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Example Usage
|
|
```typescript
|
|
// Set both SL and TP
|
|
const result = await mt4_modify_position({
|
|
ticket: 123456,
|
|
stopLoss: 2640.00,
|
|
takeProfit: 2680.00
|
|
});
|
|
|
|
// Update only take profit (trailing)
|
|
const result = await mt4_modify_position({
|
|
ticket: 123456,
|
|
takeProfit: 2700.00
|
|
});
|
|
|
|
// Set only stop loss (risk management)
|
|
const result = await mt4_modify_position({
|
|
ticket: 123456,
|
|
stopLoss: 2650.00
|
|
});
|
|
```
|
|
|
|
### Validation Rules
|
|
- At least one of stopLoss or takeProfit must be provided
|
|
- For BUY positions: stopLoss must be below takeProfit
|
|
- For SELL positions: stopLoss must be above takeProfit
|
|
|
|
### Errors
|
|
| Code | Message | Solution |
|
|
|------|---------|----------|
|
|
| - | At least one of stopLoss or takeProfit must be provided | Add SL or TP |
|
|
| - | Position with ticket {x} not found | Verify ticket number |
|
|
| - | For BUY positions, stop loss must be below take profit | Fix SL/TP levels |
|
|
|
|
---
|
|
|
|
## Common Error Responses
|
|
|
|
### Connection Error
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "MT4 terminal is not connected"
|
|
}
|
|
```
|
|
|
|
### Validation Error
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "Validation error",
|
|
"details": [
|
|
{
|
|
"path": ["symbol"],
|
|
"message": "Required"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Trading Error
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "Trade execution failed: Insufficient margin"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Usage Examples with AI Agent
|
|
|
|
### Scenario 1: Check Account and Open Trade
|
|
```
|
|
Agent: "Check my account balance and if equity is above 10000, buy 0.1 lots of XAUUSD"
|
|
|
|
1. Call mt4_get_account({})
|
|
2. Parse response, check equity > 10000
|
|
3. Call mt4_execute_trade({ symbol: "XAUUSD", action: "buy", lots: 0.1 })
|
|
```
|
|
|
|
### Scenario 2: Risk Management
|
|
```
|
|
Agent: "Set stop loss at 2640 and take profit at 2680 for my gold position"
|
|
|
|
1. Call mt4_get_positions({ symbol: "XAUUSD" })
|
|
2. Get ticket number from response
|
|
3. Call mt4_modify_position({ ticket: 123456, stopLoss: 2640, takeProfit: 2680 })
|
|
```
|
|
|
|
### Scenario 3: Close Profitable Trades
|
|
```
|
|
Agent: "Close all profitable gold positions"
|
|
|
|
1. Call mt4_get_positions({ symbol: "XAUUSD" })
|
|
2. Filter positions where profit > 0
|
|
3. For each: Call mt4_close_position({ ticket: ticketNumber })
|
|
```
|
|
|
|
---
|
|
|
|
## Version History
|
|
|
|
| Version | Date | Changes |
|
|
|---------|------|---------|
|
|
| 0.1.0 | 2026-01-04 | Initial release with 6 core tools |
|