MetaTrader MCP Server

1<div align="center">
2  <h1>MetaTrader MCP Server</h1>
3</div>
4 
5<br />
6 
7<div align="center">
8 
9[![PyPI version](https://img.shields.io/pypi/v/metatrader-mcp-server.svg?style=flat&color=blue)](https://pypi.org/project/metatrader-mcp-server/)
10[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
11[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
12 
13**Let AI assistants trade for you using natural language**
14 
15[Features](#-features) • [Quick Start](#-quick-start) • [Documentation](#-documentation) • [Examples](#-usage-examples) • [Support](#-getting-help)
16 
17![MetaTrader MCP Server](docs/media/hero.webp)
18 
19</div>
20 
21<br />
22 
23---
24 
25## 🌟 What is This?
26 
27**MetaTrader MCP Server** is a bridge that connects AI assistants (like Claude, ChatGPT) to the MetaTrader 5 trading platform. Instead of clicking buttons, you can simply tell your AI assistant what to do:
28 
29> "Show me my account balance"
30> "Buy 0.01 lots of EUR/USD"
31> "Close all profitable positions"
32 
33The AI understands your request and executes it on MetaTrader 5 automatically.
34 
35### How It Works
36 
37```
38You → AI Assistant → MCP Server → MetaTrader 5 → Your Trades
39```
40 
41## ✨ Features
42 
43- **🗣️ Natural Language Trading** - Talk to AI in plain English to execute trades
44- **🤖 Multi-AI Support** - Works with Claude Desktop, ChatGPT (via Open WebUI), and more
45- **📊 Full Market Access** - Get real-time prices, historical data, and symbol information
46- **💼 Complete Account Control** - Check balance, equity, margin, and trading statistics
47- **⚡ Order Management** - Place, modify, and close orders with simple commands
48- **🔒 Secure** - All credentials stay on your machine
49- **🌐 Flexible Interfaces** - Use as MCP server or REST API
50- **📖 Well Documented** - Comprehensive guides and examples
51 
52## 🎯 Who Is This For?
53 
54- **Traders** who want to automate their trading using AI
55- **Developers** building trading bots or analysis tools
56- **Analysts** who need quick access to market data
57- **Anyone** interested in combining AI with financial markets
58 
59## ⚠️ Important Disclaimer
60 
61**Please read this carefully:**
62 
63Trading financial instruments involves significant risk of loss. This software is provided as-is, and the developers accept **no liability** for any trading losses, gains, or consequences of using this software.
64 
65By using this software, you acknowledge that:
66- You understand the risks of financial trading
67- You are responsible for all trades executed through this system
68- You will not hold the developers liable for any outcomes
69- You are using this software at your own risk
70 
71**This is not financial advice. Always trade responsibly.**
72 
73---
74 
75## 📋 Prerequisites
76 
77Before you begin, make sure you have:
78 
791. **Python 3.10 or higher** - [Download here](https://www.python.org/downloads/)
802. **MetaTrader 5 terminal** - [Download here](https://www.metatrader5.com/en/download)
813. **MT5 Trading Account** - Demo or live account credentials
82   - Login number
83   - Password
84   - Server name (e.g., "MetaQuotes-Demo")
85 
86## 🚀 Quick Start
87 
88### Step 1: Install the Package
89 
90Open your terminal or command prompt and run:
91 
92```bash
93pip install metatrader-mcp-server
94```
95 
96### Step 2: Enable Algorithmic Trading
97 
981. Open MetaTrader 5
992. Go to `Tools` → `Options`
1003. Click the `Expert Advisors` tab
1014. Check the box for `Allow algorithmic trading`
1025. Click `OK`
103 
104### Step 3: Choose Your Interface
105 
106Pick one based on how you want to use it:
107 
108#### Option A: Use with Claude Desktop (Recommended for beginners)
109 
1101. Find your Claude Desktop config file:
111   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
112   - **Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`
113 
1142. Open the file and add this configuration:
115 
116```json
117{
118  "mcpServers": {
119    "metatrader": {
120      "command": "metatrader-mcp-server",
121      "args": [
122        "--login",    "YOUR_MT5_LOGIN",
123        "--password", "YOUR_MT5_PASSWORD",
124        "--server",   "YOUR_MT5_SERVER"
125      ]
126    }
127  }
128}
129```
130 
131**Optional: Specify Custom MT5 Terminal Path**
132 
133If your MT5 terminal is installed in a non-standard location, add the `--path` argument:
134 
135```json
136{
137  "mcpServers": {
138    "metatrader": {
139      "command": "metatrader-mcp-server",
140      "args": [
141        "--login",    "YOUR_MT5_LOGIN",
142        "--password", "YOUR_MT5_PASSWORD",
143        "--server",   "YOUR_MT5_SERVER",
144        "--path",     "C:\\Program Files\\MetaTrader 5\\terminal64.exe"
145      ]
146    }
147  }
148}
149```
150 
1513. Replace `YOUR_MT5_LOGIN`, `YOUR_MT5_PASSWORD`, and `YOUR_MT5_SERVER` with your actual credentials
152 
1534. Restart Claude Desktop
154 
1555. Start chatting! Try: *"What's my account balance?"*
156 
157#### Option B: Use with Open WebUI (For ChatGPT and other LLMs)
158 
1591. Start the HTTP server:
160 
161```bash
162metatrader-http-server --login YOUR_LOGIN --password YOUR_PASSWORD --server YOUR_SERVER --host 0.0.0.0 --port 8000
163```
164 
165**Optional: Specify Custom MT5 Terminal Path**
166 
167If your MT5 terminal is installed in a non-standard location, add the `--path` argument:
168 
169```bash
170metatrader-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
171```
172 
1732. Open your browser to `http://localhost:8000/docs` to see the API documentation
174 
1753. In Open WebUI:
176   - Go to **Settings** → **Tools**
177   - Click **Add Tool Server**
178   - Enter `http://localhost:8000`
179   - Save
180 
1814. Now you can use trading tools in your Open WebUI chats!
182 
183---
184 
185## 💡 Usage Examples
186 
187### With Claude Desktop
188 
189Once configured, you can chat naturally:
190 
191**Check Your Account:**
192> You: "Show me my account information"
193>
194> Claude: *Returns balance, equity, margin, leverage, etc.*
195 
196**Get Market Data:**
197> You: "What's the current price of EUR/USD?"
198>
199> Claude: *Shows bid, ask, and spread*
200 
201**Place a Trade:**
202> You: "Buy 0.01 lots of GBP/USD with stop loss at 1.2500 and take profit at 1.2700"
203>
204> Claude: *Executes the trade and confirms*
205 
206**Manage Positions:**
207> You: "Close all my losing positions"
208>
209> Claude: *Closes positions and reports results*
210 
211**Analyze History:**
212> You: "Show me all my trades from last week for EUR/USD"
213>
214> Claude: *Returns trade history as a table*
215 
216### With HTTP API
217 
218```bash
219# Get account info
220curl http://localhost:8000/api/v1/account/info
221 
222# Get current price
223curl "http://localhost:8000/api/v1/market/price?symbol_name=EURUSD"
224 
225# Place a market order
226curl -X POST http://localhost:8000/api/v1/order/market \
227  -H "Content-Type: application/json" \
228  -d '{
229    "symbol": "EURUSD",
230    "volume": 0.01,
231    "type": "BUY",
232    "stop_loss": 1.0990,
233    "take_profit": 1.1010
234  }'
235 
236# Get all open positions
237curl http://localhost:8000/api/v1/positions
238 
239# Close a specific position
240curl -X DELETE http://localhost:8000/api/v1/positions/12345
241```
242 
243### As a Python Library
244 
245```python
246from metatrader_client import MT5Client
247 
248# Connect to MT5
249config = {
250    "login": 12345678,
251    "password": "your_password",
252    "server": "MetaQuotes-Demo"
253}
254client = MT5Client(config)
255client.connect()
256 
257# Get account statistics
258stats = client.account.get_trade_statistics()
259print(f"Balance: ${stats['balance']}")
260print(f"Equity: ${stats['equity']}")
261 
262# Get current price
263price = client.market.get_symbol_price("EURUSD")
264print(f"EUR/USD Bid: {price['bid']}, Ask: {price['ask']}")
265 
266# Place a market order
267result = client.order.place_market_order(
268    type="BUY",
269    symbol="EURUSD",
270    volume=0.01,
271    stop_loss=1.0990,
272    take_profit=1.1010
273)
274print(result['message'])
275 
276# Close all positions
277client.order.close_all_positions()
278 
279# Disconnect
280client.disconnect()
281```
282 
283---
284 
285## 📚 Available Operations
286 
287### Account Management
288- `get_account_info` - Get balance, equity, profit, margin level, leverage, currency
289 
290### Market Data
291- `get_symbols` - List all available trading symbols
292- `get_symbol_price` - Get current bid/ask price for a symbol
293- `get_candles_latest` - Get recent price candles (OHLCV data)
294- `get_candles_by_date` - Get historical candles for a date range
295- `get_symbol_info` - Get detailed symbol information
296 
297### Order Execution
298- `place_market_order` - Execute instant BUY/SELL orders
299- `place_pending_order` - Place limit/stop orders for future execution
300- `modify_position` - Update stop loss or take profit
301- `modify_pending_order` - Modify pending order parameters
302 
303### Position Management
304- `get_all_positions` - View all open positions
305- `get_positions_by_symbol` - Filter positions by trading pair
306- `get_positions_by_id` - Get specific position details
307- `close_position` - Close a specific position
308- `close_all_positions` - Close all open positions
309- `close_all_positions_by_symbol` - Close all positions for a symbol
310- `close_all_profitable_positions` - Close only winning trades
311- `close_all_losing_positions` - Close only losing trades
312 
313### Pending Orders
314- `get_all_pending_orders` - List all pending orders
315- `get_pending_orders_by_symbol` - Filter pending orders by symbol
316- `cancel_pending_order` - Cancel a specific pending order
317- `cancel_all_pending_orders` - Cancel all pending orders
318- `cancel_pending_orders_by_symbol` - Cancel pending orders for a symbol
319 
320### Trading History
321- `get_deals` - Get historical completed trades
322- `get_orders` - Get historical order records
323 
324---
325 
326## 🔧 Advanced Configuration
327 
328### Using Environment Variables
329 
330Instead of putting credentials in the command line, create a `.env` file:
331 
332```env
333LOGIN=12345678
334PASSWORD=your_password
335SERVER=MetaQuotes-Demo
336 
337# Optional: Specify custom MT5 terminal path (auto-detected if not provided)
338# PATH=C:\Program Files\MetaTrader 5\terminal64.exe
339```
340 
341Then start the server without arguments:
342 
343```bash
344metatrader-http-server
345```
346 
347The server will automatically load credentials from the `.env` file.
348 
349### Custom Port and Host
350 
351```bash
352metatrader-http-server --host 127.0.0.1 --port 9000
353```
354 
355### Connection Parameters
356 
357The MT5 client supports additional configuration:
358 
359```python
360config = {
361    "login": 12345678,
362    "password": "your_password",
363    "server": "MetaQuotes-Demo",
364    "path": None,               # Path to MT5 terminal executable (default: auto-detect)
365    "timeout": 60000,           # Connection timeout in milliseconds (default: 60000)
366    "portable": False,          # Use portable mode (default: False)
367    "max_retries": 3,           # Maximum connection retry attempts (default: 3)
368    "backoff_factor": 1.5,      # Delay multiplier between retries (default: 1.5)
369    "cooldown_time": 2.0,       # Seconds to wait between connections (default: 2.0)
370    "debug": True               # Enable debug logging (default: False)
371}
372```
373 
374**Configuration Options:**
375 
376- **login** (int, required): Your MT5 account login number
377- **password** (str, required): Your MT5 account password
378- **server** (str, required): MT5 server name (e.g., "MetaQuotes-Demo")
379- **path** (str, optional): Full path to the MT5 terminal executable. If not specified, the client will automatically search standard installation directories
380- **timeout** (int, optional): Connection timeout in milliseconds. Default: 60000 (60 seconds)
381- **portable** (bool, optional): Enable portable mode for the MT5 terminal. Default: False
382- **max_retries** (int, optional): Maximum number of connection retry attempts. Default: 3
383- **backoff_factor** (float, optional): Exponential backoff factor for retry delays. Default: 1.5
384- **cooldown_time** (float, optional): Minimum time in seconds between connection attempts. Default: 2.0
385- **debug** (bool, optional): Enable detailed debug logging for troubleshooting. Default: False
386 
387---
388 
389## 🗺️ Roadmap
390 
391| Feature | Status |
392|---------|--------|
393| MetaTrader 5 Connection | ✅ Complete |
394| Python Client Library | ✅ Complete |
395| MCP Server | ✅ Complete |
396| Claude Desktop Integration | ✅ Complete |
397| HTTP/REST API Server | ✅ Complete |
398| Open WebUI Integration | ✅ Complete |
399| OpenAPI Documentation | ✅ Complete |
400| PyPI Package | ✅ Published |
401| Google ADK Integration | 🚧 In Progress |
402| WebSocket Support | 📋 Planned |
403| Docker Container | 📋 Planned |
404 
405---
406 
407## 🛠️ Development
408 
409### Setting Up Development Environment
410 
411```bash
412# Clone the repository
413git clone https://github.com/ariadng/metatrader-mcp-server.git
414cd metatrader-mcp-server
415 
416# Install in development mode
417pip install -e .
418 
419# Install development dependencies
420pip install pytest python-dotenv
421 
422# Run tests
423pytest tests/
424```
425 
426### Project Structure
427 
428```
429metatrader-mcp-server/
430├── src/
431│   ├── metatrader_client/      # Core MT5 client library
432│   │   ├── account/            # Account operations
433│   │   ├── connection/         # Connection management
434│   │   ├── history/            # Historical data
435│   │   ├── market/             # Market data
436│   │   ├── order/              # Order execution
437│   │   └── types/              # Type definitions
438│   ├── metatrader_mcp/         # MCP server implementation
439│   └── metatrader_openapi/     # HTTP/REST API server
440├── tests/                      # Test suite
441├── docs/                       # Documentation
442└── pyproject.toml             # Project configuration
443```
444 
445---
446 
447## 🤝 Contributing
448 
449Contributions are welcome! Here's how you can help:
450 
4511. **Report Bugs** - [Open an issue](https://github.com/ariadng/metatrader-mcp-server/issues)
4522. **Suggest Features** - Share your ideas in issues
4533. **Submit Pull Requests** - Fix bugs or add features
4544. **Improve Documentation** - Help make docs clearer
4555. **Share Examples** - Show how you're using it
456 
457### Contribution Guidelines
458 
459- Fork the repository
460- Create a feature branch (`git checkout -b feature/amazing-feature`)
461- Make your changes
462- Write or update tests
463- Ensure tests pass (`pytest`)
464- Commit your changes (`git commit -m 'Add amazing feature'`)
465- Push to the branch (`git push origin feature/amazing-feature`)
466- Open a Pull Request
467 
468---
469 
470## 📖 Documentation
471 
472- **[Developer Documentation](docs/README.md)** - Detailed technical docs
473- **[API Reference](docs/api-reference.md)** - Complete API documentation
474- **[Examples](docs/examples/)** - Code examples and tutorials
475- **[Roadmap](docs/roadmap/version-checklist.md)** - Feature development timeline
476 
477---
478 
479## 🆘 Getting Help
480 
481- **Issues**: [GitHub Issues](https://github.com/ariadng/metatrader-mcp-server/issues)
482- **Discussions**: [GitHub Discussions](https://github.com/ariadng/metatrader-mcp-server/discussions)
483- **LinkedIn**: [Connect with me](https://linkedin.com/in/ariadhanang)
484 
485### Common Issues
486 
487**"Connection failed"**
488- Ensure MT5 terminal is running
489- Check that algorithmic trading is enabled
490- Verify your login credentials are correct
491 
492**"Module not found"**
493- Make sure you've installed the package: `pip install metatrader-mcp-server`
494- Check your Python version is 3.10 or higher
495 
496**"Order execution failed"**
497- Verify the symbol exists on your broker
498- Check that the market is open
499- Ensure you have sufficient margin
500 
501---
502 
503## 📝 License
504 
505This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
506 
507---
508 
509## 🙏 Acknowledgments
510 
511- Built with [FastMCP](https://github.com/jlowin/fastmcp) for MCP protocol support
512- Uses [MetaTrader5](https://pypi.org/project/MetaTrader5/) Python package
513- Powered by [FastAPI](https://fastapi.tiangolo.com/) for the REST API
514 
515---
516 
517## 📊 Project Stats
518 
519- **Version**: 0.2.9
520- **Python**: 3.10+
521- **License**: MIT
522- **Status**: Active Development
523 
524---
525 
526<div align="center">
527 
528**Made with ❤️ by [Aria Dhanang](https://github.com/ariadng)**
529 
530⭐ Star this repo if you find it useful!
531 
532[PyPI](https://pypi.org/project/metatrader-mcp-server/) • [GitHub](https://github.com/ariadng/metatrader-mcp-server) • [Issues](https://github.com/ariadng/metatrader-mcp-server/issues)
533 
534</div>
535