TradeMCP

An MCP (Model Context Protocol) server that exposes trading analytics — technical indicators, portfolio state, risk metrics, and backtest results — as tools an LLM agent can call. Built to demonstrate protocol-level MCP understanding, not just API wrapping.

The defining design choice: read operations are open; write operations (placing trades) sit behind a human-in-the-loop approval gate. Phase 1 (this repo) ships the read-only surface and the architecture that makes the read/write split clean.

Why this exists

Most MCP portfolio projects wrap a public API in a decorator. This one is built around the questions that actually come up when you put an agent in front of something that can move money:

• What happens when the model sends a hallucinated symbol or malformed arguments?

• How do you stop an agent from doing something irreversible?

• How do you keep tool outputs small enough to not blow the context window?

• How do you swap simulated data for a live brokerage without rewriting the tools?

See DESIGN.md for the full decision record.

Related MCP server: Jesse MCP Server

Architecture

┌──────────────┐   MCP (stdio / streamable HTTP)   ┌────────────────────┐
│  LLM client  │ ───────────────────────────────►  │   TradeMCP server  │
│ (Claude etc.)│ ◄───────────────────────────────  │     (server.py)    │
└──────────────┘        tool calls / results        └─────────┬──────────┘
                                                               │ depends on interface
                                                               ▼
                                              ┌──────────────────────────────┐
                                              │   MarketDataProvider (ABC)    │
                                              ├──────────────────────────────┤
                                              │ SimulatedProvider  (default)  │
                                              │ KiteProvider       (Phase 2)  │  ← live AutoTrade Bot
                                              └──────────────────────────────┘

The tool layer depends on the MarketDataProvider interface, never on a concrete data source. That dependency-inversion boundary is what lets the same server run on simulated data in CI and live data in production.

Tools (Phase 1 — all read-only)

Every tool is annotated readOnlyHint: true and supports both markdown (default, human-readable) and json (structured) output.

Quickstart

# 1. Install
pip install -e ".[dev]"

# 2. Run the test suite
pytest

# 3. Run the server (stdio transport, the default)
python -m trade_mcp.server

# Or over HTTP for remote clients:
TRADE_MCP_TRANSPORT=streamable_http TRADE_MCP_PORT=8000 python -m trade_mcp.server

Inspect with the MCP Inspector

npx @modelcontextprotocol/inspector python -m trade_mcp.server

Wire into Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "trade-mcp": {
      "command": "python",
      "args": ["-m", "trade_mcp.server"],
      "cwd": "/absolute/path/to/trade-mcp/src"
    }
  }
}

Then ask: "What's the RSI on Reliance, and how concentrated is my portfolio?"

Data is simulated (by design)

The default SimulatedMarketDataProvider returns deterministic data derived from a hash of each input, so demos and tests are fully reproducible with zero credentials. Wiring in the live AutoTrade Bot backend means implementing the five MarketDataProvider methods in a new class and changing one line in server.py.

Roadmap

• Phase 1 — Read-only analytics surface, provider abstraction, tests

• Phase 2 — trade_place_order behind a human approval gate (Telegram confirmation + audit log)

• Phase 3 — Rate limiting, response caching, retries

• Phase 4 — Multi-server client demonstrating tool discovery/orchestration

• Phase 5 — Live KiteMarketDataProvider wrapping the real trading bot

License

MIT