Futuur API MCP Integration

Futuur MCP Server

Model Context Protocol (MCP) server for the Futuur prediction markets API. Gives Claude (and any MCP-compatible client) the ability to browse markets, simulate and place bets, manage orders, and track wager positions.

---

Quick start (recommended — Smithery)

# Claude Desktop
npx -y @smithery/cli install @futuur/futuur-mcp --client claude

# Cursor
npx -y @smithery/cli install @futuur/futuur-mcp --client cursor

Smithery will prompt you for your API keys and handle the rest.

---

Manual setup (npx — no clone needed)

1. Get API keys

Log in to futuur.com → Settings → API → generate a public/private key pair.

2. Configure your MCP client

Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "futuur": {
      "command": "npx",
      "args": ["-y", "@futuur/futuur-mcp"],
      "env": {
        "FUTUUR_PUBLIC_KEY": "your_public_key_here",
        "FUTUUR_PRIVATE_KEY": "your_private_key_here"
      }
    }
  }
}

Claude Code (CLI) — run once to register the server:

claude mcp add futuur -- npx -y @futuur/futuur-mcp \
  -e FUTUUR_PUBLIC_KEY=your_public_key_here \
  -e FUTUUR_PRIVATE_KEY=your_private_key_here

Or add to .claude/settings.json under "mcpServers" using the same format as Claude Desktop above.

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "futuur": {
      "command": "npx",
      "args": ["-y", "@futuur/futuur-mcp"],
      "env": {
        "FUTUUR_PUBLIC_KEY": "your_public_key_here",
        "FUTUUR_PRIVATE_KEY": "your_private_key_here"
      }
    }
  }
}

4. Restart your client

Claude Desktop / Cursor need a full restart after editing config files.

---

Available tools

Market discovery

Tool	Description
get_markets	List/search events with filters (category, tag, status, ordering, etc.)
get_market_details	Full details for a single event including all nested markets
get_categories	List market categories (legacy v1 endpoint)
get_category_details	Details for a specific category
get_price_history	Historical price data for an event (day, week, month, year, all_time)

Account

Tool	Description
get_user_profile	Authenticated user profile and balances
get_user_ranking	Your position on the leaderboard

Trading

Tool	Description
get_bet_simulation	Preview a limit order (cost/shares) without placing it
place_bet	Execute a limit order using a confirmed simulation payload
list_orders	List your open/filled/cancelled orders
cancel_order	Cancel an open order by ID

Positions (wagers)

Tool	Description
get_user_bets	List your wager positions with optional filters
get_wager_details	Full details for a single wager
get_partial_sell_amount	Simulate proceeds from selling N shares
sell_bet	Sell all or part of a wager position

---

Typical workflow with Claude

1. "Show me the top 10 markets by volume"           → get_markets
2. "Give me details on event #1234"                 → get_market_details
3. "Simulate buying 100 OOM on the Yes outcome"     → get_bet_simulation (requires event_id + market_id)
4. "Looks good, place the bet"                      → place_bet
5. "Show my open positions"                         → get_user_bets
6. "How much would I get if I sold 50 shares?"      → get_partial_sell_amount
7. "Sell them"                                      → sell_bet

Tip: Use play_money mode (currency_mode: "play_money") to test without risking real funds. OOM is the play money currency.

---

Authentication

All authenticated requests use HMAC-SHA512 signatures. The server handles this automatically — just provide your public and private keys via environment variables (FUTUUR_PUBLIC_KEY / FUTUUR_PRIVATE_KEY).

Public endpoints (events listing, event details) do not require authentication.

---

API reference

Full API documentation: docs.futuur.com
OpenAPI schema (machine-readable): api.futuur.com/docs/schema/

---

Development

npm run dev      # Run with tsx (hot reload)
npm run build    # Compile TypeScript
npm run start    # Run compiled build
npm test         # Run tests

Troubleshooting

See docs/TROUBLESHOOTING.md.

---