trading-mcp-server

A local MCP (Model Context Protocol) server that exposes safe trading tools for AI agents such as Claude Code and Copilot CLI. The agent does the reasoning; this server provides market data, technical indicators, news, sizing helpers, a paper-trading engine, backtesting, and a guarded broker layer (Angel One SmartAPI, NSE).

Execution model — one switch, three modes (EXECUTION_MODE):

• notify — place_order returns a manual-placement recommendation (and a Telegram alert if configured). Nothing is executed.
• paper — place_order fills in a simulated paper account. (default)
• live — place_order places a real order — but only when ALLOW_LIVE_TRADING=true (a human-only switch in .env; no tool can change it). With it off, live orders degrade to notify.

Safety guarantees:

• The broker is reached only when EXECUTION_MODE=live and ALLOW_LIVE_TRADING=true.
• Delivery (CNC) sell is never sent to the broker in any mode — it always degrades to a notify recommendation so the user can verify holdings and sell manually.
• Every order decision is appended to an audit log (storage/trade_logs.jsonl).

Where trading policy lives: risk limits, intraday/swing selection, and position sizing are not in the server — they live in a client-side trading_config.yaml that your agent reads and enforces. The server only validates that orders are structurally well-formed. See docs/CLIENT_INTEGRATION.md.

Nothing produced by this server is financial advice.

Installation

# local development (editable, from a sibling checkout)
pip install -e ../trading-mcp-server

# with broker + scanner extras (needed for live data / Chartink watchlist)
pip install -e "../trading-mcp-server[broker,scanners]"

# future, once published to PyPI
pip install trading-mcp-server

Requires Python 3.10+.

Running the server

The server speaks MCP over stdio:

trading-mcp-server
# or
python -m trading_mcp_server.server

It resolves its configuration and state from a home directory:

1. TRADING_MCP_HOME environment variable, if set
2. otherwise the current working directory

There it reads <home>/.env (execution mode, the live master switch, broker credentials) and writes <home>/storage/ (paper-trading state, audit log). This keeps the package independent of any repo path — point TRADING_MCP_HOME at your trading project.

Register in a client (e.g. .mcp.json for Claude Code):

{
  "mcpServers": {
    "trading-agent": {
      "command": "trading-mcp-server",
      "env": { "TRADING_MCP_HOME": "C:\\path\\to\\your\\trading-repo" }
    }
  }
}

What it exposes

Tools (by category)

To open a position use place_order (it routes to the paper engine in paper mode, the broker in live mode, or a recommendation in notify mode). Risk policy is enforced by your agent via trading_config.yaml — see docs/CLIENT_INTEGRATION.md.

Resources

• trading://config — current configuration (secrets redacted)
• trading://safety-rules — the safety rules the server enforces

Prompts

• intraday_trade_analysis(symbol) — disciplined intraday workflow
• swing_trade_analysis(symbol) — swing/delivery workflow
• paper_trading_review() — profitability review workflow

Backtest strategies built in: ma_crossover, rsi_reversal, macd_trend, breakout_volume.

Package structure

src/trading_mcp_server/
├── server.py        # FastMCP entry point (create_server, main)
├── config.py        # .env-backed TradingConfig — single source of truth
├── tools/           # MCP tool modules (one per category, register(mcp))
├── resources/       # MCP resources
├── prompts/         # MCP prompts
├── services/        # data provider, indicators, risk, validation, paper engine, broker safety layer
├── broker/          # SmartAPI adapter — the ONLY module talking to the real broker
├── backtest/        # engine + built-in strategies
└── utils/           # logging/audit, market hours, instrument lookup
tests/               # pytest suite (config, safety, paper engine, indicators, backtest)

Development

pip install -e ".[dev]"
python -m pytest tests -q          # run tests (no network, no broker needed)
python -m trading_mcp_server.server  # run server from source

Configuration reference

The server reads only a few execution switches from <home>/.env (template: examples/.env.example):

Trading policy (risk limits, intraday/swing, sizing) is not here — it lives in a client-side trading_config.yaml read by your agent. Template: examples/trading_config.example.yaml. Full guide: docs/CLIENT_INTEGRATION.md.

Publishing to PyPI (future)

1. Bump version in pyproject.toml and src/trading_mcp_server/__init__.py.
2. python -m build (requires pip install build).
3. python -m twine upload dist/* (requires a PyPI account + API token).
4. Consumers then switch from pip install -e ../trading-mcp-server to pip install trading-mcp-server — no other change needed.

License

MIT