Trading 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)

Category	Tools
Config	get_trading_config, get_execution_mode, set_execution_mode, update_trading_config
Market data	fetch_live_price, fetch_historical_data, fetch_market_status, fetch_symbol_metadata, fetch_watchlist
Indicators	calculate_sma/ema/rsi/macd/bollinger_bands/atr/volume_analysis, detect_support_resistance, detect_trend, get_indicator_snapshot
News	fetch_latest_news, fetch_market_news, get_market_sentiment, get_sector_sentiment, fetch_news_articles, analyze_news_sentiment
Portfolio	fetch_portfolio, fetch_order_history, calculate_portfolio_exposure, calculate_unrealized_pnl
Risk (calculators)	calculate_position_size, calculate_stop_loss, calculate_target_price, check_max_daily_loss, check_portfolio_concentration
Strategy	evaluate_intraday_trade_setup, evaluate_swing_trade_setup, compare_multiple_symbols, scan_watchlist_for_intraday_opportunities, scan_watchlist_for_swing_opportunities, run_strategy_backtest
Paper trading	close_paper_position, fetch_paper_trades, fetch_paper_portfolio, calculate_paper_trading_performance, generate_paper_trading_report, reset_paper_account
Order execution	place_order (routes by EXECUTION_MODE)
Broker (read)	fetch_broker_funds, fetch_broker_positions, fetch_broker_holdings, fetch_broker_order_status
Notifications	send_notification (Telegram+Discord fan-out), send_telegram_notification, send_discord_notification, send_trade_alert

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):

Key	Values	Notes
EXECUTION_MODE	notify | paper | live	the one switch; default paper
ALLOW_LIVE_TRADING	true | false	human-only; live orders place only when true
NOTIFY_PAPER_ORDERS	true | false	Telegram alert on paper fills
PAPER_STARTING_CAPITAL	number	paper engine capital
BROKER_*	secrets	Angel One credentials (live + live data)
NEWS_API_KEY	secret	optional news search
TELEGRAM_BOT_TOKEN/TELEGRAM_CHAT_ID	secrets	Telegram notifications
DISCORD_TOKEN/DISCORD_CHANNEL_ID	secrets	Discord notifications

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