AI Trading MCP is a news-trading rig that treats the LLM as its only signal source and the backtest-kit engine as its only executor. A GramJS scraper pipes a live Telegram channel — text posts and chart screenshots alike — straight into Claude through the MCPDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/theonetrade/ai-trading-mcp/llms.txt
Use this file to discover all available pages before exploring further.
get_status feed. Claude then decides when and which way to trade using exactly three tools. Everything else — take-profit, stop-loss, entry cost, symbol validation — is computed and enforced engine-side, beyond the model’s reach.
Key Features
Quickstart
Clone, build, authorize Telegram, and have a paper-trading portfolio talking to Claude in minutes.
Architecture Overview
Understand the two-process design: the stdio MCP server that holds no state and the trading process that owns all of it.
MCP Tools Reference
Full specification for
get_status, open_position, and close_position — the agent’s entire vocabulary.Telegram Feed
How GramJS scrapes posts and chart screenshots, queues concurrent fetches, and handles timeouts safely.
Paper Trading
Run the full rig against real Binance market data with simulated fills — no API keys required.
Live Trading
Flip to real Binance spot execution and learn how the battle-hardened broker adapter survives exchange edge cases.
Loop Mode
Run the rig unattended with Claude Code’s
/loop command — an interval-driven news-trader that watches the feed and acts on signals automatically.Environment Variables
Full reference for every configurable variable: Telegram credentials, symbol whitelist, MCP bridge address, and optional Redis/MongoDB backends.
The Three-Tool Contract
The agent’s entire vocabulary is three tools. Nothing else is exposed — not position sizing, not leverage, not withdrawals.| Tool | Arguments | What the agent receives |
|---|---|---|
get_status | — | One message per traded symbol: current price, invested balance, queued entry, active position with unrealized PnL, and queued close — plus the last 15 Telegram posts as text and MCP image blocks |
open_position | symbol, position (long | short), note | Market entry with engine-computed TP/SL and cost. Rejected if the symbol is not whitelisted or already holds a position or pending signal |
close_position | symbol, note | Queues a market close. Fails if there is nothing to close |
note argument is the model’s audit trail: whatever reasoning or Telegram signal the agent records there is echoed back in every subsequent status, and persisted to disk in the markdown dumps.
Transport success is not operation success. Every tool call returns an envelope where
error is either an empty string or the engine’s exact rejection message — the agent reads it and can react accordingly.What the Engine Owns
The deliberate design choice of this project is that the strategy file registers no entry logic at all — only logging callbacks. All trading intelligence lives in two places: the LLM (signal decisions) and the engine (execution rules). The engine owns: Take-profit, stop-loss, and entry cost. These are computed engine-side on everyopen_position call and cannot be overridden or even suggested by the model. The agent calls open_position(symbol, "short", note) and receives a fill confirmation; the bracket levels are invisible to it.
The validation chain. An open call passes through MCP → strategy → risk profiles → actions before any order is placed. A symbol outside the whitelist is simply untradable, regardless of what the Telegram feed says.
The symbol whitelist. Controlled by the CC_SYMBOL_LIST environment variable, defaulting to 13 pairs:
Live.background() instance runs per symbol, each independently tracking candles, signals, and persistence state.
Duplicate-open rejection. An open_position call against a symbol that already holds a position or a pending signal is rejected by the engine, not by prompt engineering. The blast radius of any single model decision is bounded structurally.
Persistence across restarts. Live state is written under dump/data/ — signals, storage, notifications, recent, memory, state, and session records all survive a process restart. An open position, its OCO brackets, and the full history of what the model saw are all still there when the process comes back up.