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
{
"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
// 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
{
"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
// 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
{
"success": true,
"data": {
"symbol": "XAUUSD",
"bid": 2650.50,
"ask": 2650.80,
"spread": 0.30,
"timestamp": "2026-01-04T12:00:00.000Z"
}
}
Example Usage
// 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
{
"success": true,
"data": {
"success": true,
"ticket": 123456,
"message": "Order placed successfully",
"symbol": "XAUUSD",
"action": "buy",
"lots": 0.1
}
}
Example Usage
// 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
{
"success": true,
"data": {
"success": true,
"ticket": 123456,
"message": "Position closed"
}
}
Example Usage
// 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
{
"success": true,
"data": {
"success": true,
"ticket": 123456,
"message": "Position modified successfully"
}
}
Example Usage
// 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
{
"success": false,
"error": "MT4 terminal is not connected"
}
Validation Error
{
"success": false,
"error": "Validation error",
"details": [
{
"path": ["symbol"],
"message": "Required"
}
]
}
Trading Error
{
"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 |
