Skip to main content
Glama
Trading-MCP-Server

Trading-MCP-Server

README.md
# ⚔ Trading-MCP-Server: Institutional Model Context Protocol Server

[![CI & Code Quality](https://github.com/jahanzaib-codes/Trading-MCP-Server/actions/workflows/ci.yml/badge.svg)](https://github.com/jahanzaib-codes/Trading-MCP-Server/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%20%7C%203.11-blue.svg)](https://www.python.org/)
[![FastMCP](https://img.shields.io/badge/FastMCP-2.x-brightgreen.svg)](https://github.com/modelcontextprotocol)
[![Docker Ready](https://img.shields.io/badge/docker-ready-blue.svg)](Dockerfile)

> **Institutional Model Context Protocol (FastMCP 2.x) trading server connecting Claude Desktop, Cursor, and LLM coding assistants to multi-broker execution backends (IBKR, Binance, Alpaca). Exposes portfolio analytics, order validation, quantitative Kelly sizing, and streaming market telemetry.**

---

## šŸ›ļø System Architecture

```
ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”
│     LLM Clients (Claude Desktop, Cursor, Agent Swarm)  │
ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”¬ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜
                            │ Standard I/O (JSON-RPC)
                            ā–¼
ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”
│               Trading-MCP-Server Core                  │
│                                                        │
│  ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”            ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”  │
│  │   MCP Tools      │            │   MCP Resources  │  │
│  │  • get_quote     │            │  • portfolio://  │  │
│  │  • get_portfolio │            │  • risk-limits   │  │
│  │  • validate_risk │            │  • health        │  │
│  │  • compute_size  │            ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜  │
│  ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”¬ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜                                  │
│           │                                            │
│           ā–¼                                            │
│  ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”  │
│  │     Pre-Trade Risk Engine & Quantitative Math    │  │
│  │  • Fat-Finger Guard ($50k)   • Kelly Criterion   │  │
│  │  • Max Leverage Cap (3x)     • 30D HV & ATR(14)  │  │
│  │  • Single-Asset Cap (25%)    • 1D Parametric VaR │  │
│  ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”¬ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜  │
ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”¼ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜
                            │
         ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”¼ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”
         ā–¼                  ā–¼                  ā–¼
ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”
│ Interactive     ││ Binance         ││ Alpaca Markets  │
│ Brokers (TWS)   ││ (Spot/Futures)  ││ (Paper/Live)    │
ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜
```

---

## šŸš€ Key Features

* **Universal Model Context Protocol Support:** Implements native MCP tools and resources compliant with Anthropic Claude Desktop, Cursor AI, Cline, and custom agent swarms.
* **Pre-Trade Risk Guardian:** Automatically intercepts and inspects every order before transmission:
  * Fat-finger limits (default: \$50,000 max single order).
  * Buying power verification and margin utilization guards.
  * Single-asset portfolio concentration cap (25% default).
  * Circuit breaker lockdown upon daily drawdown threshold breach.
* **Quantitative Sizing Engine:** Volatility-adjusted position sizing using the Kelly Criterion, Historical Annualized Volatility (HV30), and Average True Range (ATR14).
* **Multi-Broker Adapters:**
  * **Interactive Brokers:** TWS / Gateway socket and Client Portal API.
  * **Binance:** Real-time crypto quotes and Futures margin tracking.
  * **Alpaca Markets:** US Equities and commission-free paper/live execution.

---

## šŸ“‹ Available MCP Tools & Resources

### MCP Tools (Callable by Claude & Cursor)
| Tool Name | Parameters | Description |
| :--- | :--- | :--- |
| `get_quote` | `symbol`, `broker` | Returns real-time bid, ask, last price, spread, and 24h change. |
| `get_portfolio` | `broker` | Returns Net Liquidation Value, cash, margin, and open positions. |
| `validate_risk` | `symbol`, `action`, `quantity`, `price`, `broker` | Validates proposed trade against hard pre-trade risk gates. |
| `compute_position_size`| `symbol`, `equity`, `risk_pct`, `entry`, `stop_loss` | Computes optimal share count and capital allocation. |
| `compute_volatility` | `symbol` | Computes 30-day volatility, ATR14, and daily expected move. |

### MCP Resources
* `trading://health`: Health status and latency telemetry across all broker connections.
* `trading://risk-limits`: Current institutional parameters and circuit breaker status.

---

## šŸ’» Claude Desktop & Cursor Integration

### 1. Claude Desktop Setup
Add the server configuration to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "Trading-MCP-Server": {
      "command": "python",
      "args": [
        "-m",
        "src.server"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "IBKR_HOST": "127.0.0.1",
        "IBKR_PORT": "7497",
        "MAX_ORDER_NOTIONAL_USD": "50000.0"
      }
    }
  }
}
```

### 2. Cursor AI Setup
Add to your project's `.cursor/mcp.json`:

```json
{
  "mcp": {
    "servers": {
      "Trading-MCP-Server": {
        "command": "python",
        "args": ["main.py"],
        "transport": "stdio"
      }
    }
  }
}
```

---

## ⚔ Quickstart & Interactive Demonstration

### 1. Installation
```bash
git clone https://github.com/jahanzaib-codes/Trading-MCP-Server.git
cd Trading-MCP-Server
pip install -r requirements.txt
cp .env.example .env
```

### 2. Interactive Terminal Demo
Run the automated end-to-end institutional test suite:
```bash
python cli.py demo
```

```text
================================================================================
   ⚔ TRADING-MCP-SERVER: INSTITUTIONAL DEMONSTRATION SUITE
================================================================================

[1/5] Broker Connector Telemetry:
| Broker               | Status    | Endpoint                 |
|----------------------|-----------|--------------------------|
| Interactive Brokers  | CONNECTED | 127.0.0.1:7497           |
| Binance Spot/Futures | CONNECTED | api.binance.com          |
| Alpaca Markets       | CONNECTED | paper-api.alpaca.markets |

[2/5] Real-Time Multi-Asset Market Data Quotes:
| Symbol   | Asset Class   | Bid        | Ask        | Last       | Spread          | 24h Chg   |
|----------|---------------|------------|------------|------------|-----------------|-----------|
| NVDA     | EQUITY        | $142.58    | $142.62    | $142.60    | $0.04 (0.028%)  | +1.24%    |
| SPY      | EQUITY        | $585.31    | $585.49    | $585.40    | $0.18 (0.031%)  | +1.24%    |
| BTCUSDT  | CRYPTO        | $88,445.57 | $88,454.43 | $88,450.00 | $8.85 (0.01%)   | +3.85%    |
| SOLUSDT  | CRYPTO        | $214.19    | $214.21    | $214.20    | $0.02 (0.0093%) | +3.85%    |
```

### 3. Individual CLI Commands
```bash
# Fetch live quote for NVDA
python cli.py quote NVDA --broker ibkr

# Inspect Binance portfolio
python cli.py portfolio --broker binance

# Calculate volatility-adjusted position size
python cli.py size --symbol NVDA --equity 100000 --risk 1.5 --entry 142.60 --stop 135.00
```

---

## 🐳 Docker Deployment

Run as an isolated container:
```bash
docker compose up -d --build
```

---

## šŸ‘Øā€šŸ’» Author & Institutional Consulting

Developed by **Jahanzaib** — Quantitative Finance, Algorithmic Trading Systems, and AI Agent Architect.

* **Fiverr:** [https://www.fiverr.com/jahanzaib313110](https://www.fiverr.com/jahanzaib313110)
* **Telegram:** [@JanzebBlockdev](https://t.me/JanzebBlockdev)
* **GitHub:** [@jahanzaib-codes](https://github.com/jahanzaib-codes)

For private institutional deployments, custom broker integrations, or proprietary risk modeling, reach out via Fiverr or Telegram.

---

## šŸ“„ License
This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.