# TradeZylo MCP Server

> **Give Claude / Cursor / Antigravity IDE full intelligence, analytics, and journal action access to your TradeZylo trading data.**

## 38 Tools — 7 Domains (Reads, Writes & Structural Actions)

| Domain | Count | Tools |
|---|---|---|
| **Trades** | 6 | `get_trades`, `get_trade_detail`, `get_trade_screenshots`, `log_trade` *(write)*, `update_trade` *(write)*, `close_trade` *(write)* |
| **Analytics** | 6 | `get_overview_stats`, `get_mae_mfe_stats`, `get_edge_by_market`, `get_edge_by_direction`, `get_fee_leakage`, `get_ai_insights` |
| **Psychology** | 5 | `get_emotion_pnl`, `get_mistake_audit`, `get_checklist_score`, `get_planned_rr`, `add_mistake` *(write)* |
| **Risk** | 5 | `get_risk_limits`, `get_risk_check`, `update_limits` *(write)*, `freeze_trading` *(action)*, `unfreeze_trading` *(action)* |
| **Playbook** | 4 | `get_playbook`, `get_strategy_stats`, `get_playbook_rules`, `add_strategy` *(write)* |
| **Accounts** | 8 | `get_accounts`, `get_active_account`, `switch_account` *(action)*, `get_drawdown_stats`, `get_account_comparison`, `create_account` *(write)*, `pause_account` *(action)*, `resume_account` *(action)* |
| **Journal** | 4 | `get_daily_notes`, `get_trade_calendar`, `search_notebook`, `save_daily_review` *(write)* |

---

## 4 AI Workflow Prompts (Slash-Command Routines)

Trigger pre-built institutional trading routines in Claude Desktop or Cursor with 1 click or by typing `/`:

| Prompt | Timing | Purpose |
|---|---|---|
| **`pre_market_routine`** | Morning | Checks daily risk limits, verifies open swing positions, reviews active playbook setup rules, and runs a 3-point mental readiness check. |
| **`post_session_review`** | Evening | Reviews closed trades, calculates win rate & PnL, audits execution mistakes, and drafts a structured journal review to save via `save_daily_review`. |
| **`psychology_deep_dive`** | Mindset Audit | Deep-dives into emotional leaks (`get_emotion_pnl`), calculates dollar loss from recurring mistakes (`get_mistake_audit`), and guides tilt prevention. |
| **`strategy_playbook_audit`** | Weekend / Strategy | Evaluates strategy edge, win rate, and holding efficiency (`get_mae_mfe_stats`) to optimize entry/exit rules and record updates. |

---

## Quick Start

### 1. Install dependencies

```bash
cd web/mcp
npm install
```

### 2. Build

```bash
npm run build
```

### 3. Generate your MCP API Key

Go to TradeZylo Dashboard → **MCP Server** (`/mcp`) in your sidebar:
1. Click **Generate New Key**
2. Copy your key (starts with `tzm_`)
3. You can also copy the ready-to-use JSON config directly from that page!

### 4. Configure Claude Desktop / Cursor

Add to your `claude_desktop_config.json` or Cursor MCP settings:

```json
{
  "mcpServers": {
    "tradezylo": {
      "command": "node",
      "args": ["d:/SAAS APPS PENDING/TRADEZYLO/web/mcp/dist/index.js"],
      "env": {
        "TRADEZYLO_API_URL": "http://localhost:3001",
        "TRADEZYLO_TOKEN": "PASTE_YOUR_TOKEN_HERE"
      }
    }
  }
}
```

### 5. Or run in dev mode (tsx, no build needed)

```bash
cd web/mcp
TRADEZYLO_API_URL=http://localhost:3001 TRADEZYLO_TOKEN=your_token npm run dev
```

---

## Example Conversations with Claude

Once connected, you can ask Claude things like:

- *"Show me my last 20 FOREX trades with PnL"*
- *"Log my EURUSD trade: entered long at 1.0850, stop 1.0820, target 1.0920, 1 lot"*
- *"Tag 'FOMO' mistake with high impact on trade #102"*
- *"Save morning prep notes: watching CPI release at 8:30am, bias bullish on NAS100"*
- *"Add 'Liquidity Sweep Reversal' strategy to my playbook"*
- *"Update my daily loss limit to $750 and max risk per trade to 1.5%"*
- *"Freeze trading for 24 hours: on tilt after 3 consecutive losses"*
- *"Create a new trading account 'FTMO $100k Phase 1' with $100,000 initial balance"*
- *"What's my win rate this month and fee leakage across brokers?"*
- *"Am I close to my daily loss limit today?"*

---

## Architecture

```
Claude / Cursor / Antigravity IDE
        ↓  stdio (MCP Protocol)
   TradeZylo MCP Server (web/mcp)
        ↓  HTTP + Bearer JWT
   TradeZylo Fastify Backend (:3001)
        ↓  Prisma ORM
   PostgreSQL Database
```

## Security & Integrity Notes

- **Zero Real Broker Risk**: TradeZylo is an analytics and journaling platform. MCP write tools mutate your TradeZylo journal database only; they cannot touch exchange accounts or live broker funds.
- **Full Populated Records**: All write tools return complete, populated records rather than simple acknowledgments.
- **Audit Logging**: Every write action (`log_trade`, `update_trade`, `close_trade`, `add_mistake`, `save_daily_review`, `add_strategy`, `update_limits`, `freeze_trading`, `create_account`) is appended to `logs/mcp-audit.log` with timestamp and payload details.
- **Token Stays Local**: Your JWT/API key is stored only in your local environment variables and is never transmitted to third parties.
- **Local stdio**: The server runs strictly via local stdio communication rather than exposing an open network port.