📈 Riffmax-TradingBot-AI-RiffEx

Autonomous AI Trading Agent powered by Python and MetaTrader 5 (MT5) MCP — real-time market structure analysis, automated signal generation, intelligent order execution, and strict risk guardrails.

]()

📌 What it does

Riffmax-TradingBot-AI-RiffEx is an autonomous trading agent that operates directly on MetaTrader 5 (MT5) using Python and the Model Context Protocol (MCP):

• 📊 Real-Time Market Analysis — Ingests live tick data, OHLCV candles, order books, and open positions directly through MT5 MCP tools.
• 🧠 AI Decision Engine — Analyzes price action, market liquidity, and volatility metrics using Python-based quantitative models and LLM agent reasoning.
• ⚡ Direct Order Execution — Places, tracks, modifies, and closes market and pending orders programmatically via the MT5 MCP interface.
• 🛡️ Autonomous Risk Guardrails — Enforces dynamic lot sizing based on account equity, automatic stop-loss (SL), take-profit (TP), maximum drawdown thresholds, and spread filtering.
• 📝 Structured Logging & Auditing — Records all signal evaluations, execution payloads, and deal receipts in JSON/CSV audit trails.

🏗️ Architecture

┌────────────────────────────────────────────────────────┐
│             AI Agent Decision Layer (Python)           │
│   • Technical Analysis  • Price Action  • Volatility   │
└───────────────────────────┬────────────────────────────┘
                            │
               Model Context Protocol (MCP)
                            │
┌───────────────────────────▼────────────────────────────┐
│                    MT5 MCP Server                      │
│   • get_candles_latest   • get_account_info            │
│   • place_market_order   • modify_position             │
└───────────────────────────┬────────────────────────────┘
                            │
┌───────────────────────────▼────────────────────────────┐
│               MetaTrader 5 (MT5) Terminal              │
│       Broker Execution · Live Market Liquidity         │
└────────────────────────────────────────────────────────┘

🛠️ Stack

🚀 Quick Start

Prerequisites

• Python 3.10+
• MetaTrader 5 terminal installed and logged into your broker account
• MT5 MCP server configured

1. Clone & Install

git clone https://github.com/Riffmax2030-hub/Riffmax-TradingBot-AI-RiffEx.git
cd Riffmax-TradingBot-AI-RiffEx
pip install -r requirements.txt

2. Configure Environment

cp .env.example .env
# Edit .env with your credentials — NEVER commit real .env files

.env.example template:

MT5_ACCOUNT=your_account_number
MT5_PASSWORD=your_password
MT5_SERVER=your_broker_server
MAX_RISK_PER_TRADE_PERCENT=1.0
MAX_DAILY_DRAWDOWN_PERCENT=3.0

3. Run the Trading Agent

python main.py

📁 Project Structure

Riffmax-TradingBot-AI-RiffEx/
├── agent/
│   ├── market_analyzer.py    # Price action & indicator analysis
│   ├── decision_engine.py    # Signal generation logic
│   ├── mcp_bridge.py         # MT5 Model Context Protocol interface
│   └── risk_guard.py         # Dynamic lot sizing & risk limits
├── config/
│   └── config.yaml           # Symbol lists, timeframe, max spread
├── logs/                     # Trade logs & audit trails (gitignored)
├── tests/
│   ├── test_market_analyzer.py
│   └── test_risk_guard.py
├── .env.example              # Template with placeholders
├── .gitignore                # Excludes credentials, logs, caches
├── requirements.txt
└── README.md

🔐 Security & Risk Disclaimer

[!CAUTION] Financial & Credential Security: - Never hardcode broker account numbers, server details, or passwords in code or commits. - All sensitive configurations are loaded strictly via environment variables. - Trading financial markets carries risk. Use a demo account for testing before any live deployment.

📄 License

MIT © Sherif Akanmu