# mcp-market-server

MCP (Model Context Protocol) server exposing **live crypto market data** and a
**paper-trading engine** as standardized tool calls — so any agent (Claude Code,
custom multi-agent systems) can query Bybit and execute simulated trades.

Built for the Tower Research Capital AI/ML intern application: demonstrates
MCP integration, agent tool-calling, risk controls, and production-style Python.

## Architecture

```
┌─────────────┐     MCP stdio      ┌──────────────────┐    REST     ┌─────────┐
│ Claude Code │ ◄───────────────► │  FastMCP Server  │ ─────────►  │  Bybit  │
│   / Agent   │                    │  (tools.py)      │  public API │   v5    │
└─────────────┘                    └────────┬─────────┘             └─────────┘
                                            │
                                   ┌────────▼─────────┐
                                   │  Paper Engine    │
                                   │  SQLite + Risk   │
                                   └──────────────────┘
```

## Tools Exposed

| Tool | Description |
|------|-------------|
| `get_klines` | OHLCV candles for any symbol/timeframe |
| `get_orderbook` | L2 order book snapshot |
| `get_ticker` | Latest price / 24h stats |
| `place_paper_order` | Market/limit order into paper engine (risk-guarded) |
| `cancel_order` | Cancel an open paper order |
| `get_positions` | Open positions + unrealized P&L |
| `get_orders` | Open/filled order history |
| `close_position` | Flatten a position at market |
| `get_account` | Cash balance, equity, realized/unrealized P&L |

## Risk Guards (paper engine)

- Max notional per order (`risk.max_order_notional_usd`)
- Max open positions (`risk.max_open_positions`)
- Daily loss halt — trading disabled once daily drawdown exceeds cap
- Every order + decision is written to an audit log table

## Setup

```bash
cd mcp-market-server
python -m venv .venv && .venv\Scripts\activate     # Windows
pip install -e ".[dev]"
cp .env.example .env                                # optional overrides
pytest                                              # run tests
```

## Register with Claude Code

```json
{
  "mcpServers": {
    "market": {
      "command": "python",
      "args": ["-m", "mcp_market_server.server"],
      "cwd": "/absolute/path/to/mcp-market-server"
    }
  }
}
```

Or with the CLI:

```bash
claude mcp add market -- python -m mcp_market_server.server
```

## Demo Prompts (after registering)

```
Fetch the last 100 hourly candles for BTCUSDT and summarize the trend.

Place a paper long of 0.01 BTCUSDT with a 2% stop loss and take profit at 3%.

Show my account, then flatten everything if unrealized PnL is worse than -$50.
```

## Design Notes

- **Public endpoints only** — no API keys, no real money. Paper engine fills
  market orders against live ticker price, limit orders when price touches.
- **SQLite** for orders/positions/trades/audit — zero-dependency persistence,
  mirrors how quant desks log every decision.
- **Risk layer sits between tools and engine** — same pattern as a real desk:
  strategy proposes, risk disposes.