# 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](docs/CLIENT_INTEGRATION.md).

> Nothing produced by this server is financial advice.

## Installation

```bash
# 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:

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

```json
{
  "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](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

```bash
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`](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`](examples/trading_config.example.yaml).
Full guide: [docs/CLIENT_INTEGRATION.md](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