Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/backtest-kit/ai-trading-mcp/llms.txt

Use this file to discover all available pages before exploring further.

AI Trading MCP is an MCP server and trading engine that gives Claude a deliberately constrained vocabulary for crypto trading: exactly three tools — get_status, open_position, and close_position. Built on backtest-kit, it pairs a GramJS Telegram scraper (text posts and chart screenshots) with a production-grade Binance spot broker, while every decision the model makes is logged to disk before it leaves the process.

​
Design Philosophy

The central principle is a clean division of responsibility: the LLM is the only signal source; the engine owns all risk. The bundled strategy registers no entry logic whatsoever — positions are opened exclusively when the agent calls open_position. Everything else is engine-side and cannot be overridden by the model:
  • Take-profit and stop-loss are computed from engine-side risk profiles, not from the agent’s prompt.
  • Position sizing is fixed per trade and set in configuration.
  • Symbol whitelist (CC_SYMBOL_LIST, 13 pairs by default) is enforced at the transport layer — a symbol outside the list cannot be traded regardless of what the feed says.
  • Duplicate-open rejection happens in the engine’s validation chain, not via prompt engineering.
This makes the guardrails structural. Swapping the LLM, rewriting the system prompt, or feeding in adversarial instructions cannot widen the agent’s vocabulary past those three tools.

​
How It Differs from a Naive Trading Bot

A naive approach puts all safety logic in the prompt and trusts the model to obey it. AI Trading MCP inverts that: the engine acts as a gatekeeper that validates every open_position and close_position call against its own rules before touching the broker. An open against a symbol that already holds a position or a pending signal is rejected by the engine — the agent receives an isError tool result with the engine’s exact message and can react accordingly.

​
Two Modes: Paper and Live

ModeCommand flagFillsMarket data
Paper--paperSimulated in the engineReal Binance via ccxt
Live--liveReal Binance spot ordersReal Binance via ccxt
Paper mode needs no API keys — the engine simulates fills while pulling real price data. Flipping to --live activates the full spot broker adapter with guaranteed entry, atomic OCO brackets, and idempotent recovery logic.

​
The Telegram Feed as a Sensory Organ

Every get_status response includes the last 15 posts from the configured Telegram channel, newest first, each stamped with its ISO timestamp. Photo posts are labelled explicitly so the model never has to guess whether an image is present. Chart screenshots ride along as MCP image blocks — the scraper selects the smallest Telegram photo size with width ≥ 800 px, balancing readability against payload weight. The feed is treated as untrusted input by design. Instructions embedded in posts are data, not commands — the engine’s validation chain and symbol whitelist bound the blast radius of any single model decision.

​
Full Audit Trail

Every get_status response is dumped to disk before it leaves the process: text to dump/mcp/<minute-stamp>.md, images to dump/images/<id>.png referenced relatively so the markdown renders in any viewer — including the web dashboard on :60050. Position notes carry the model’s stated basis, and the engine echoes them back in every subsequent status, so the full chain of reasoning is always recoverable.

​
The Deliberately Empty Strategy

The strategy file content/manual.strategy/manual.strategy.ts registers no signal logic — only logging callbacks for onOpen, onClose, and onActivePing. Entries happen only when the agent explicitly calls open_position. This is intentional: the LLM is the signal source, and the empty strategy makes that boundary visible in the code. 
import { addStrategySchema } from "backtest-kit";

addStrategySchema({
  strategyName: "main_strategy",
  callbacks: {
    onOpen(symbol, { priceOpen, priceStopLoss, priceTakeProfit, position }, currentPrice) {
      console.log("Position opened", { symbol, position, priceOpen, priceTakeProfit, priceStopLoss, currentPrice });
    },
    onClose(symbol, { priceOpen, priceStopLoss, priceTakeProfit, position }, currentPrice) {
      console.log("Position closed", { symbol, position, priceOpen, priceTakeProfit, priceStopLoss, currentPrice });
    },
    onActivePing(symbol, { priceOpen, priceStopLoss, priceTakeProfit, position }, currentPrice) {
      console.log("Position active", { symbol, position, priceOpen, priceTakeProfit, priceStopLoss, currentPrice });
    },
  },
});
Each callback receives the full signal object — priceOpen, priceStopLoss, priceTakeProfit, and position — computed entirely by the engine. The strategy cannot modify these values; it can only observe them.

​
Schema Registration Overview

Three schema registrations wire the system together across the two workspace packages:
FunctionFilePurpose
addMCPSchemapackages/agent/src/config/setup.tsRegisters manual_mcp — the get_status renderer that composes portfolio state, command history, and the Telegram feed into MCP tool results
addStrategySchemacontent/manual.strategy/manual.strategy.tsRegisters main_strategy — empty signal logic, logging-only callbacks
addExchangeSchemacontent/manual.strategy/modules/paper.module.ts (paper) or live.module.ts (live)Registers ccxt-exchange — Binance market data, or Binance spot execution in live mode
serve() (imported from @backtest-kit/mcp, called at the end of config/setup.config.ts) starts the HTTP bridge on 127.0.0.1:60051 that connects the stdio MCP server to the trading process. Live.background() is called once per symbol in CC_SYMBOL_LIST (13 pairs by default) to start the engine loop for that symbol.

​
Explore the Docs

Quickstart

Install, authorize Telegram, run a paper trade, and attach Claude in under 10 minutes.

Architecture

How the two-process model, HTTP bridge, and error envelope fit together.

get_status Reference

What the agent receives on every status call: portfolio state, feed posts, and image blocks.

Spot Broker Adapter

Guaranteed entry, atomic OCO brackets, and idempotent recovery for live Binance trading.

Build docs developers (and LLMs) love

Get started for freeTalk to us