parsec-mcp

MCP server for trading and monitoring prediction markets across Polymarket, Kalshi, Opinion, Limitless, and PredictFun — from any AI assistant.

Search markets, stream live orderbooks, preview and place trades, and manage your portfolio through natural language. Works with Claude Desktop, Cursor, VS Code Copilot, Cline, Windsurf, and any MCP-compatible client.

Quick Start

PARSEC_API_KEY=pk_live_... npx parsec-mcp serve

Get your API key at parsecapi.com.

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "parsec": {
      "command": "npx",
      "args": ["-y", "parsec-mcp", "serve"],
      "env": {
        "PARSEC_API_KEY": "pk_live_..."
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "parsec": {
      "command": "npx",
      "args": ["-y", "parsec-mcp", "serve"],
      "env": {
        "PARSEC_API_KEY": "pk_live_..."
      }
    }
  }
}

VS Code / Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "parsec": {
      "command": "npx",
      "args": ["-y", "parsec-mcp", "serve"],
      "env": {
        "PARSEC_API_KEY": "pk_live_..."
      }
    }
  }
}

Windsurf / Cline

Add to your MCP configuration:

{
  "mcpServers": {
    "parsec": {
      "command": "npx",
      "args": ["-y", "parsec-mcp", "serve"],
      "env": {
        "PARSEC_API_KEY": "pk_live_..."
      }
    }
  }
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | PARSEC_API_KEY | Yes | Your Parsec API key (pk_live_... or pk_test_...) | | PARSEC_API_BASE_URL | No | Override API base URL (default: https://api.parsecapi.com) | | PARSEC_DISABLE_WALLET_EXPORT | No | Set to 1 to disable the wallet key export tool | | PARSEC_MCP_ENABLE_RAW | No | Set to 1 to enable the advanced raw API escape hatch |

Tools

Composite Tools (Start Here)

High-level tools designed for AI agents — these handle market resolution, multi-step workflows, and formatting automatically.

| Tool | Description | |------|-------------| | parsec.market.find_market | Search for markets by keyword, parsec_id, or exchange-native ID | | parsec.market.get_market_snapshot | Get market metadata + orderbook + recent trades in one call | | parsec.trade.preview_order | Simulate an order with execution price and balance context | | parsec.account.get_trading_setup_status | Check if the account is ready to trade | | parsec.stream.open_market_feed | One-step real-time WebSocket feed setup |

Market Data

| Tool | Description | |------|-------------| | parsec.market.list_exchanges | List supported exchanges and their status | | parsec.market.list_markets | Search, filter, and resolve markets with cursor pagination | | parsec.market.get_orderbook | Live bid/ask levels for a market outcome | | parsec.market.get_execution_price | Estimate fill price for a hypothetical order | | parsec.market.get_price | Current mid-market price for an outcome | | parsec.market.list_trades | Recent trades for a market | | parsec.market.list_events | List multi-market event groups |

Trading

| Tool | Description | |------|-------------| | parsec.trade.create_order | Place a live order on any exchange | | parsec.trade.cancel_order | Cancel an open order | | parsec.trade.list_orders | List orders with status/exchange filters | | parsec.trade.get_order | Get order details by ID | | parsec.trade.list_positions | Current open positions | | parsec.trade.list_fills | Executed trade fills | | parsec.trade.get_balance | Exchange balance (total, available, reserved) |

Real-Time Streaming

Stream live orderbook snapshots, deltas, and trade activity over WebSocket.

| Tool | Description | |------|-------------| | parsec.stream.open_market_feed | One-step feed setup (recommended) | | parsec.stream.connect | Open a WebSocket session | | parsec.stream.auth | Authenticate a session | | parsec.stream.subscribe | Subscribe to market feeds | | parsec.stream.unsubscribe | Remove subscriptions | | parsec.stream.resync | Request orderbook resync | | parsec.stream.read | Read buffered messages | | parsec.stream.close | Close a session |

Account & Wallet

| Tool | Description | |------|-------------| | parsec.account.ping | Check API connectivity | | parsec.account.get_usage | API usage stats | | parsec.account.get_ws_usage | WebSocket usage stats | | parsec.account.get_user_activity | Recent account activity | | parsec.account.onboard | Complete account onboarding | | parsec.wallet.get_state | Wallet and exchange link status | | parsec.wallet.export_key | Export wallet private key (sensitive) |

Builder (Multi-Tenant)

For platforms building on top of Parsec with per-user isolation.

| Tool | Description | |------|-------------| | parsec.builder.create_user | Create an end-user | | parsec.builder.list_users | List all end-users | | parsec.builder.get_user | Get end-user details | | parsec.builder.update_user | Update end-user profile | | parsec.builder.delete_user | Delete an end-user (irreversible) | | parsec.builder.onboard_user | Onboard end-user for trading | | parsec.builder.get_pool | Liquidity pool status | | parsec.builder.get_escrow_config | Escrow configuration |

Polymarket CTF

Advanced conditional token operations (most users should use create_order instead).

| Tool | Description | |------|-------------| | parsec.ctf.split | Split USDC into conditional tokens | | parsec.ctf.merge | Merge tokens back into USDC | | parsec.ctf.redeem | Redeem winning tokens after resolution |

Example Prompts

Once connected, try asking your AI assistant:

• "What prediction markets are available about Bitcoin?"
• "Show me the orderbook for the Trump 2028 market on Polymarket"
• "What's my Kalshi balance?"
• "Preview buying 50 Yes contracts on that market"
• "Open a live feed for the ETH price market"
• "Am I set up to trade?"

Security

• API key is passed via environment variable, never in tool calls
• Sensitive tools (create_order, cancel_order, export_key) are annotated as destructive
• Wallet export can be disabled globally with PARSEC_DISABLE_WALLET_EXPORT=1
• Internal endpoints are never exposed through the MCP surface
• All connections use HTTPS/WSS

Troubleshooting

"PARSEC_API_KEY is required" — Set the environment variable in your MCP client configuration.

Tools not appearing — Restart your MCP client after configuration changes. Check that npx parsec-mcp serve runs successfully in your terminal.

Authentication errors — Verify your API key at parsecapi.com. Test keys (pk_test_...) work in sandbox mode only.

WebSocket session limit — Max 8 concurrent sessions. Close unused sessions with parsec.stream.close.

Development

npm install
npm run build
npm test
npm run check          # build + test + contract tests
npm run eval:smoke     # smoke test harness

License

MIT