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（命令行）— 运行一次以注册服务：

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 的相同格式，将其添加到 .claude/settings.json 的 "mcpServers" 下。

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。

---