traderspost-mcp

TradersPost MCP Server

An MCP (Model Context Protocol) server that gives Claude direct access to TradersPost webhook trading.

Send trade signals, inspect strategy configs, query trade history, and monitor positions — all without leaving Claude Code or Claude Desktop.

Why this exists: TradersPost doesn't expose a full REST management API. This MCP server wraps their webhook system and, optionally, a local prop_futures_relay installation to give Claude a complete trading management interface.

---

What It Does

17 MCP tools covering the full trading workflow:

| Category | Tools | |----------|-------| | Strategy management | tp_list_strategies, tp_get_strategy, tp_toggle_strategy | | Signal submission | tp_send_signal | | Trade history (SQLite) | tp_get_recent_trades, tp_get_fills, tp_get_trade_stats | | Position state | tp_get_positions, tp_get_daily_pnl | | Health & status | tp_get_relay_health, tp_get_strategy_health, tp_system_status, tp_eval_status | | Control (destructive) | tp_flatten_all, tp_flatten_strategy, tp_pause_engine, tp_resume_engine |

Response envelope

Every tool returns one shape. ok reflects semantic success, not the HTTP status — a TradersPost HTTP 200 with success: false is a rejection and returns ok: false.

// success
{ "ok": true,  "data": { /* result */ }, /* ...extras */ }
// failure
{ "ok": false, "code": "machine_code", "detail": "human readable", /* ... */ }

Plus two MCP resources:

• traderspost://signal-format — webhook payload reference
• traderspost://active-accounts — account config summary

---

Modes

Relay mode (recommended)

Point RELAY_DIR at a local prop_futures_relay installation. The server reads account_config.yaml, state JSON files, and trading_system.db for full functionality.

Standalone mode

Set TP_WEBHOOK_<STRATEGY> env vars directly. Signal sending works; strategy management and trade history tools return empty results.

---

Installation

Requirements: Python 3.10+

git clone https://github.com/AdairBear/traderspost-mcp.git
cd traderspost-mcp
pip install -r requirements.txt

Or install dependencies directly:

pip install "mcp[cli]" httpx pyyaml python-dotenv

---

Configuration

Claude Code (.claude/settings.json)

Relay mode — with a local prop_futures_relay installation:

{
  "mcpServers": {
    "traderspost": {
      "command": "python",
      "args": ["/path/to/traderspost-mcp/traderspost_mcp.py"],
      "env": {
        "RELAY_DIR": "/path/to/prop_futures_relay"
      }
    }
  }
}

Standalone mode — webhook URLs only:

{
  "mcpServers": {
    "traderspost": {
      "command": "python",
      "args": ["/path/to/traderspost-mcp/traderspost_mcp.py"],
      "env": {
        "TP_WEBHOOK_MY_STRATEGY": "https://traderspost.io/trading/webhook/...",
        "RELAY_URL": "https://relay.yourdomain.app"
      }
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)

{
  "mcpServers": {
    "traderspost": {
      "command": "python",
      "args": ["/path/to/traderspost-mcp/traderspost_mcp.py"],
      "env": {
        "RELAY_DIR": "/path/to/prop_futures_relay"
      }
    }
  }
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | RELAY_DIR | No | Path to a local prop_futures_relay installation. Enables strategy config, state files, and SQLite access. | | TP_WEBHOOK_* | Yes (per strategy) | TradersPost webhook URLs. In relay mode, the strategy's webhook_ref field names these. In standalone mode, use TP_WEBHOOK_<STRATEGY_UPPER>. | | RELAY_URL | No | Base URL of your running relay (e.g. https://relay.yourdomain.app). Required for health check tools. |

Copy .env.example to .env and fill in your values:

cp .env.example .env

The server auto-loads .env from RELAY_DIR first, then from its own directory.

---

Tool Reference

tp_list_strategies

List all configured strategies with their status, ticker, account, and webhook configuration.

Returns: JSON with strategy list, account summary, and aliases.
Note: webhook URLs are never exposed — only whether they're configured.

tp_get_strategy

Get full configuration for a specific strategy including account rules and session window.

Args:
  strategy (str): Strategy key, e.g. "sil_crusher_tradovate_44942793"

tp_toggle_strategy

Enable or disable a strategy in account_config.yaml.

Args:
  strategy (str): Full strategy key
  enabled (bool): True to enable, False to disable

Note: Modifies local config only — restart or redeploy the relay for changes to take effect.

tp_send_signal ⚠️

Send a trade signal to TradersPost. Dry-run by default — pass live=True to place a real order.

Args:
  strategy (str): Strategy key (or standalone env var suffix)
  ticker (str):   Instrument — "MNQ", "SIL", "MGC", "ES", etc.
  action (str):   "buy", "sell" (entries), "exit", "cancel" (exits)
  quantity (int): Number of contracts (default: 1)
  sentiment (str, optional): "bullish", "bearish", or "flat"
  order_type (str, optional): "market", "limit", or "stop"
  take_profit (float, optional): Take profit price level
  stop_loss (float, optional): Stop loss price level
  live (bool):  True = REAL order. Default False = dry-run preview only.
  test (bool, optional): Force dry-run. If True, overrides live=True (safety wins).

Replay safety: every attempt is logged to a JSONL audit file (TP_ATTEMPT_LOG) before the POST. An identical live entry (buy/sell) within TP_DEDUP_WINDOW_SEC (default 30s) is refused to prevent a timeout-retry duplicate order.

Exits are sacred: exit/cancel are never deduplicated, fire even on a disabled strategy, and a rejected exit always fails loud (ok: false).

tp_get_recent_trades

Query recent trade signals and TradersPost HTTP responses from SQLite.

Args:
  limit (int): Max records 1-100, default 20
  strategy (str, optional): Filter by strategy
  account_id (str, optional): Filter by account
  days (int, optional): Lookback window in days

tp_get_fills

Query actual fill data (execution prices, slippage) from the fills table.

Args: Same as tp_get_recent_trades

tp_get_trade_stats

Aggregate statistics: signal success rates, slippage summary, per-strategy breakdown.

Args:
  strategy (str, optional): Filter by strategy
  account_id (str, optional): Filter by account
  days (int): Lookback period, default 30

tp_get_positions

Get current position state from relay state JSON files, or falls back to relay API.

Returns: Per-strategy state: FLAT / IN_POSITION / PENDING_ENTRY / PENDING_EXIT / HALTED

tp_get_daily_pnl

Get today's estimated P&L from the relay's daily loss tracker.

Returns: Per-account estimated P&L and remaining loss budget.
Note: Estimated from signals, not confirmed broker fills.

tp_get_relay_health

Check relay health via the /health endpoint.

Requires: RELAY_URL env var
Returns: Relay version, uptime, component status

tp_get_strategy_health

Get per-strategy status (signal counts, last signal time, halts) from the running relay.

Requires: RELAY_URL env var
Returns: Per-strategy status from /health/strategies

---

Usage Examples

Check what's configured

"Show me all configured strategies and which ones have webhooks set up"
→ Claude calls tp_list_strategies()

Dry-run a signal

"Send a test buy signal for SIL, 1 contract, to the sil_crusher_tradovate_44942793 strategy"
→ Claude calls tp_send_signal(strategy="sil_crusher_tradovate_44942793", ticker="SIL",
    action="buy", quantity=1, test=True)

Monitor performance

"How many signals has sil_crusher sent this week and what's the success rate?"
→ Claude calls tp_get_trade_stats(strategy="sil_crusher_tradovate_44942793", days=7)

Emergency disable

"Disable the MNQ strategy immediately"
→ Claude calls tp_toggle_strategy(strategy="coord_mnq_gmr_tradovate_44942793", enabled=False)

Check positions and P&L

"What positions are currently open and what's today's P&L?"
→ Claude calls tp_get_positions() and tp_get_daily_pnl()

---

Security Notes

• Webhook URLs are read from environment variables and never appear in tool responses or logs
• tp_send_signal is marked destructiveHint: true — Claude will confirm before calling it
• test=True returns the TradersPost trade plan without executing any orders — use it first
• tp_toggle_strategy only modifies local config — the running relay is not affected until redeployed

---

Architecture

Claude (MCP client)
    ↓ stdio
traderspost_mcp.py (MCP server)
    ├── account_config.yaml   (strategy config — RELAY_DIR mode)
    ├── data/state/*.json     (position state — RELAY_DIR mode)
    ├── trading_system.db     (trade history — RELAY_DIR mode)
    ├── TP_WEBHOOK_* env vars (webhook URLs — always)
    └── RELAY_URL/health      (live relay status — optional)
         ↓ httpx POST
    TradersPost webhook
         ↓
    Broker (Tradovate, etc.)

---

Requirements

• Python 3.10+
• mcp[cli] >= 1.0 (FastMCP)
• httpx >= 0.24
• pyyaml >= 6.0
• python-dotenv >= 1.0 (optional, for .env auto-loading)

---

License

MIT — see LICENSE.