Futuur API MCP Integration

Futuur MCP サーバー

Futuurの予測市場 API 用 Model Context Protocol（MCP）サーバーです。Claude（および MCP 対応クライアント）で、市場の閲覧、ベットのシミュレーションと実行、注文の管理、賭けポジションの追跡ができます。

---

クイックスタート（推奨 — 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 が API キーの入力を求め、残りの設定を処理します。

---

手動セットアップ（npx — クローン不要）

1. API キーを取得する

futuur.comにログインし、Settings → API に移動して、公開鍵と秘密鍵のペアを生成します。

2. MCP クライアントを設定する

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %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）— 以下を一度実行して、サーバーを登録します。

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

または、Claude Desktop と同じ形式で、"mcpServers"の下にある.claude/settings.jsonに追加します。

Cursor — .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. クライアントを再起動する

設定ファイルを編集した後は、Claude Desktop／Cursor を完全に再起動する必要があります。

---

利用可能なツール

市場の探索

ツール	説明
get_markets	フィルター（カテゴリ、タグ、ステータス、並べ替えなど）を指定して、イベントを一覧表示／検索します
get_market_details	ネストされたすべての市場を含む、単一イベントの詳細を取得します
get_categories	市場カテゴリを一覧表示します（旧 v1 エンドポイント）
get_category_details	指定したカテゴリの詳細を取得します
get_price_history	イベントの価格履歴データを取得します（day、week、month、year、all_time）

アカウント

ツール	説明
get_user_profile	認証済みユーザーのプロフィールと残高を取得します
get_user_ranking	リーダーボード上の順位を取得します

取引

ツール	説明
get_bet_simulation	指値注文を発注せずに、事前確認します（コスト／シェア数）
place_bet	確認済みのシミュレーションデータを使って、指値注文を実行します
list_orders	未約定／約定済み／キャンセル済みの注文を一覧表示します
cancel_order	ID を指定して未約定の注文をキャンセルします

ポジション（賭け）

ツール	説明
get_user_bets	オプションのフィルターを指定して、賭けポジションを一覧表示します
get_wager_details	単一の賭けの詳細を取得します
get_partial_sell_amount	N シェアを売却した場合の受取額をシミュレーションします
sell_bet	賭けポジションの全部または一部を売却します

---

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

ヒント： リアルマネーを使わずにテストするには、play_moneyモード（currency_mode: "play_money"）を使用してください。OOM はプレイマネーの通貨です。

---

認証

認証が必要なリクエストでは、すべて HMAC-SHA512 署名を使用します。サーバーが自動的に処理するため、環境変数（FUTUUR_PUBLIC_KEY／FUTUUR_PRIVATE_KEY）で公開鍵と秘密鍵を指定するだけです。

公開エンドポイント（イベント一覧、イベント詳細）では認証は不要です。

---

API リファレンス

API ドキュメント全文：docs.futuur.com
OpenAPI スキーマ（機械可読）：api.futuur.com/docs/schema/

---

開発

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

トラブルシューティング

docs/TROUBLESHOOTING.mdを参照してください。

---