TradeOdds MCP Server

Connect TradeOdds historical pattern analysis + direct SQL query access to Claude Desktop, Cursor, or any MCP-compatible AI agent.

v3.1.1 (2026-05-26): Patch — accepts null on optional response fields (analysis_1d/5d/20d, observed_move, sector). The previous schema used .optional() which rejected null, causing "Invalid structured content" errors on factor-match scans that included low-data symbols. Output is also cleaned to omit null fields so downstream agents don't need to special-case null vs missing.

v3.1 (2026-05-26): factor_match and analyze_stock now expose all 17 DNA conditions (previously 7 and 12 respectively — unknown keys were silently stripped). factor_match.daily_change default flipped from true to false so screening calls no longer secretly add exact-bucket daily-change matching. Adds price_tolerance, vix_tolerance, and history_range params to factor_match. Upgrade with npm install -g tradeodds-mcp@latest or re-run npx -y tradeodds-mcp@latest.

What it does

Four tools, returning both human-readable text AND structured JSON content blocks (so capable LLMs parse fields directly without re-prompting):

• list_symbols — Browse the ~3,200 available tickers (stocks, ETFs, crypto). Free.
• analyze_stock — Run historical pattern analysis on a single symbol. Pro+.
• factor_match — Scan all symbols for pattern matches under current conditions. Pro+.
• query (new in v3) — Run arbitrary SELECT against the TradeOdds DB. 30+ years of bitmasked market history, 16 indexed factor columns, precomputed forward returns. Power User+ only. Billed in compute credits (1 per second of query time, minimum 1).

Setup

1. Get an API key

Sign up at tradeodds.io. Pick a tier based on what you want the agent to do:

• Pro ($29/mo) — list_symbols + analyze_stock + factor_match
• Power User ($99/mo) — adds query (3,000 query credits/mo)
• Quant ($299/mo) — query + 12,000 credits/mo + priority compute lane + bulk export

Create an API key from Account → API keys.

2. Claude Desktop / Claude Code

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "tradeodds": {
      "command": "npx",
      "args": ["-y", "tradeodds-mcp"],
      "env": {
        "TRADEODDS_API_KEY": "${env:TRADEODDS_API_KEY}"
      }
    }
  }
}

Restart Claude Desktop. Or download the pre-filled config from https://tradeodds.io/api-docs (the "Claude Desktop / Claude Code" card).

3. Cursor

Same JSON, drop it into ~/.cursor/mcp.json. Or download from /api-docs.

4. Run directly

The standard npx tradeodds-mcp invocation in the config above handles install

• launch automatically. If you'd rather pin a version, use ["-y", "[email protected]"].

Reproducing dashboard Factor Match scans

The web dashboard applies a few defaults that this MCP server intentionally does not assume — so a "same conditions" scan can return different counts:

| Setting | Dashboard default (paid) | MCP / API default | Pass via MCP | |---|---|---|---| | filters.price_min | 10 | 10 (since v3.1; was null) | filters: { price_min: 10 } | | price_tolerance | 1 | 0 | price_tolerance: 1 | | vix_tolerance | 1 | 0 | vix_tolerance: 1 | | daily_change default | false | false (since v3.1; was true) | conditions: { daily_change: false } | | Popular Settings preset | {magnitude, vix_level, regime, rsi_zone, rsi_slope, rel_vol} | — | pass each true explicitly |

Environment variables

| Variable | Required | Description | |---|---|---| | TRADEODDS_API_KEY | Yes | Your API key from tradeodds.io/account | | TRADEODDS_BASE_URL | No | API base URL (default: https://tradeodds-production.up.railway.app) |

Example usage

Once connected, ask your agent:

• "What's the historical outcome when SPY drops 2% in a day?" (uses analyze_stock)
• "Run a factor match — high-liquidity names with bullish regime + RSI oversold, win rate over 60% on 5-day forward." (uses factor_match)
• "Query the DB: every day NVDA had RSI bucket -2 and VIX bucket >= 3 since 2020, with the 5d forward return." (uses query — Power User+)
• "Find the top 10 symbols by 5d win rate in the technology sector for VIX collapse days." (uses query)

Pricing & limits

v1 tools (analyze_stock, factor_match, list_symbols)

• list_symbols: Free, no rate limit
• analyze_stock: $0.05/call via Stripe meter (Pro tier and above). 1,000/day cap, 10 concurrent.
• factor_match: $0.15/call via Stripe meter. 200/day cap, 2 concurrent.
• MCP requests bypass the per-call meter — included with Pro+ subscription. Equivalent calls via raw REST API are metered.

v2 query tool (Power User+)

Billed in compute credits (not per-call):

| Tier | Monthly credits | Row cap / query | Concurrent | |---|---:|---:|---:| | power_user ($99/mo) | 3,000 | 100,000 | 3 | | quant ($299/mo) | 12,000 | 1,000,000 + bulk export | 5 |

• 1 credit per second of compute, minimum 1 per query
• 10-minute server-side cache — repeats of the same query are free
• Buy a credit pack for overage: $99 = 2,000 credits, $299 = 7,000 credits (expire 6 months)

Full docs: https://tradeodds.io/api-docs · Schema reference · 16-factor catalog

License

MIT