metatrader-mcp-server
CLAUDE.md824 starsChanged 14 months agoMITView on GitHub
MCP server enabling AI assistants to trade on MetaTrader 5 via natural language. Provides both MCP (stdio) and HTTP/REST interfaces. Stack: Python 3.10+ • FastMCP • FastAPI • MetaTrader5 SDK • Pandas • Pydantic • pytest Version: 0.5.1 (Beta) Repo: https://github.com/ariadng/metatrader-mcp-server Pattern: Functions receive connection as first param, use keyword-only args (*,)
The file
We split this CLAUDE.md into the rules it gives an agent
8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 134
Add to <module>/__init__.py and client_<module>.py
- Distinctive: line 163
Use type hints and docstrings for all public functions
- Very specific: line 165
Use keyword-only args (*,) for clarity
- Distinctive: line 167
Test with demo accounts
- Very specific: line 169
Update __init__.py when adding modules
- Very specific: line 176
Use print() (use logging)
- Distinctive: line 177
Test with live accounts without consent
- Distinctive: line 178
Add emojis unless requested
≈ “Common” is an estimate: at least 1 in 5 of the 26,980 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Claude Development Guide - MetaTrader MCP Server
Project Overview
MCP server enabling AI assistants to trade on MetaTrader 5 via natural language. Provides both MCP (stdio) and HTTP/REST interfaces.
Stack: Python 3.10+ • FastMCP • FastAPI • MetaTrader5 SDK • Pandas • Pydantic • pytest Version: 0.5.1 (Beta) Repo: https://github.com/ariadng/metatrader-mcp-server
Architecture (3 Packages)
1. metatrader_client - Core MT5 Library
metatrader_client/
├── account/ # Balance, equity, margin operations
├── connection/ # MT5 connection management with retry/cooldown
├── history/ # Historical deals and orders
├── market/ # Prices, candles, symbols
├── order/ # Trade execution and position management
├── types/ # Enums (OrderType, Timeframe, TradeAction, etc.)
└── client.py # Main MT5Client classPattern: Functions receive connection as first param, use keyword-only args (*,)
def place_market_order(connection, *, type: str, symbol: str, volume: Union[float, int]):2. metatrader_mcp - MCP Server
- FastMCP with SSE transport (default), STDIO fallback via
--transport stdio - Tools:
@mcp.tool()decorated functions - Client access:
client = get_client(ctx) - Returns: CSV strings for DataFrames, dicts for objects
3. metatrader_openapi - REST API
- FastAPI with OpenAPI docs at
/docs - Routers: accounts, market, orders, positions, history
- Client:
request.app.state.client - CORS enabled, lifespan-managed connection
Key Conventions
Code Style
# Function pattern
def operation(connection, *, param: type, optional: Optional[type] = None):
"""Brief description.
Args:
connection: MT5 connection object
param: Description
optional: Description (default: None)
Returns:
dict: {"error": bool, "message": str, "data": Any}
"""Return Formats
- Client operations:
{"error": False, "message": "...", "data": {...}}(dict) or DataFrame - MCP tools:
df.to_csv()for DataFrames, dict/list for objects - REST endpoints:
df.to_dict(orient="records")or dict (auto JSON)
Import Order
- Standard library (
os,typing) - Third-party (
pandas,fastapi) - Local (
.exceptions,.types)
Common Patterns
Connection
from metatrader_client import MT5Client
# Minimal configuration
config = {"login": int(login), "password": password, "server": server}
# Full configuration with all available options
config = {
"login": int(login), # Required: MT5 account login
"password": password, # Required: MT5 account password
"server": server, # Required: MT5 server name
"path": None, # Optional: Path to terminal executable (auto-detect if None)
"timeout": 60000, # Optional: Connection timeout in ms (default: 60000)
"portable": False, # Optional: Use portable mode (default: False)
"max_retries": 3, # Optional: Max connection retries (default: 3)
"backoff_factor": 1.5, # Optional: Retry delay multiplier (default: 1.5)
"cooldown_time": 2.0, # Optional: Seconds between connections (default: 2.0)
"debug": False # Optional: Enable debug logging (default: False)
}
client = MT5Client(config)
client.connect()
# operations...
client.disconnect()Error Handling
# Client level
if type.upper() not in ["BUY", "SELL"]:
return {"error": True, "message": "Invalid type", "data": None}
# API level
try:
return client.operation()
except MT5ConnectionError as e:
raise HTTPException(status_code=503, detail=str(e))Testing Pattern
@pytest.fixture(scope="module")
def mt5_client():
client = MT5Client({"login": int(os.getenv("LOGIN")), ...})
client.connect()
yield client
client.disconnect()Adding New Features
New Client Operation
- Create
metatrader_client/<module>/new_operation.py - Add to
<module>/__init__.pyandclient_<module>.py - Test in
tests/metatrader_client/test_<module>.py
New MCP Tool
- Add to
metatrader_mcp/server.py:
@mcp.tool()
def tool_name(ctx: Context, param: type) -> str:
"""Description for AI."""
client = get_client(ctx)
result = client.module.operation(param)
return result.to_csv() if hasattr(result, 'to_csv') else resultNew REST Endpoint
- Add to
metatrader_openapi/routers/<module>.py:
@router.post("/path", response_model=Dict[str, Any])
async def endpoint(request: Request, param: type = Body(...)):
"""Description."""
client = request.app.state.client
return client.module.operation(param)Critical Rules
✅ DO
- Use type hints and docstrings for all public functions
- Return consistent formats:
{"error": bool, "message": str, "data": Any} - Use keyword-only args (
*,) for clarity - Handle exceptions with custom exception classes
- Test with demo accounts
- Validate inputs (symbols, volumes, prices)
- Update
__init__.pywhen adding modules
❌ DON'T
- Hardcode credentials (use env vars)
- Mix business logic with routing
- Skip error handling on trading operations
- Modify connection object in functions
- Use
print()(use logging) - Test with live accounts without consent
- Add emojis unless requested
MetaTrader 5 Specifics
Order Types: BUY, SELL, BUY_LIMIT, SELL_LIMIT, BUY_STOP, SELL_STOP, BUY_STOP_LIMIT, SELL_STOP_LIMIT Timeframes: M1, M5, M15, M30, H1, H4, D1, W1, MN1 Filling Modes: Broker-dependent (FOK, IOC, Return) Platform: Windows-centric (MT5 terminal required) Symbol Format: Broker-dependent (e.g., "EURUSD", "EURUSD.m")
Environment Variables
Required: LOGIN, PASSWORD, SERVER
Optional: MT5_PATH (path to MT5 terminal executable, auto-detected if not set), OPENAPI_TITLE, OPENAPI_VERSION
MCP Transport: MCP_TRANSPORT (sse|stdio|streamable-http, default: sse), MCP_HOST (default: 0.0.0.0), MCP_PORT (default: 8080)
Debug: Set debug: True in config dict
Testing & Debugging
# Run tests
pytest tests/ # All
pytest tests/metatrader_client/ # Client only
pytest tests/test_orders_route.py # Specific
# Debug
client.is_connected() # Check connection
client.get_terminal_info() # Terminal details
client.last_error() # Get last errorProject Goals
- Accessibility - Natural language trading for non-programmers
- Modularity - Independent, reusable components
- Safety - Prevent accidental losses through validation
- Reliability - Robust error handling and connection management
- Extensibility - Easy to add operations and integrations
Resources
- MCP Spec: https://spec.modelcontextprotocol.io/
- FastMCP: https://github.com/jlowin/fastmcp
- MT5 Python: https://www.mql5.com/en/docs/python_metatrader5
- FastAPI: https://fastapi.tiangolo.com/
Note: This is financial software. Changes can result in real money loss. Test thoroughly with demo accounts.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

