Trading-MCP-Server
README.md
# ā” Trading-MCP-Server: Institutional Model Context Protocol Server
[](https://github.com/jahanzaib-codes/Trading-MCP-Server/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/)
[](https://github.com/modelcontextprotocol)
[](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.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues