技术文档摘要

Polymarket MCP 服务器

这是一个使用 Rust 构建的高性能模型上下文协议（MCP）服务器，用于处理 Polymarket 预测市场数据。该服务器通过 MCP 工具、资源和提示提供实时市场数据、价格和投注信息。

功能

• 🔄 实时市场数据：获取活跃市场、热门市场及详细的市场信息
• 🔍 高级搜索：通过关键词在问题、描述和类别中搜索市场
• 💰 价格信息：获取当前的“是”/“否”价格和市场统计数据
• 📊 MCP 资源：自动刷新市场数据资源并具有智能缓存功能
• 🤖 AI 驱动提示：市场分析、套利检测和交易见解
• ⚡ 高性能：内置缓存、连接池优化速度
• 🔧 灵活配置：环境变量、TOML 文件或默认设置
• 🏗️ 生产就绪：零编译警告、全面错误处理、全测试覆盖

快速开始

先决条件

• Rust 1.70+ - 通过 rustup 安装
• Claude Desktop - 从 Claude.ai 下载
• 互联网连接 - 用于访问 Polymarket API（无需 API 密钥）

安装

方案 1：下载预构建二进制文件（推荐）

1. 下载最新版本 适用于您的平台：

   • 访问 发布页面
   • 下载适合您操作系统的二进制文件

2. 配置 Claude Desktop：

   编辑您的 Claude Desktop 配置文件：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

   添加 Polymarket MCP 服务器：

   {
     "mcpServers": {
       "polymarket": {
         "command": "/path/to/polymarket-mcp/target/release/polymarket-mcp",
         "env": {
           "RUST_LOG": "info"
         }
       }
     }
   }
   

3. 重启 Claude Desktop 加载新的 MCP 服务器。

方案 2：从源代码构建

1. 克隆并构建：

   git clone https://github.com/0x79de/polymarket-mcp
   cd polymarket-mcp
   cargo build --release
   

2. 在您的 Claude Desktop 配置中使用二进制文件 target/release/polymarket-mcp。

方案 3：Docker 部署

1. 构建 Docker 镜像：

   docker build -t polymarket-mcp:latest .
   

2. 配置 Claude Desktop 使用 Docker：

   编辑您的 Claude Desktop 配置文件：

   # macOS
   vim ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
   # Windows
   notepad %APPDATA%\Claude\claude_desktop_config.json
   
   # Linux
   nano ~/.config/Claude/claude_desktop_config.json
   

   添加 Docker 配置：

   {
     "mcpServers": {
       "polymarket": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "-e", "RUST_LOG=info",
           "-e", "POLYMARKET_CACHE_TTL=300",
           "polymarket-mcp:latest"
         ],
         "env": {
           "RUST_LOG": "info"
         }
       }
     }
   }
   

3. 重启 Claude Desktop 加载新的 MCP 服务器。

方案 4：通过 Cargo 安装

cargo install --git https://github.com/0x79de/polymarket-mcp

二进制文件将安装到 ~/.cargo/bin/polymarket-mcp。

配置（可选）

服务器开箱即用，具有合理的默认值。基本使用不需要任何配置。

环境变量

创建一个 .env 文件以进行自定义配置：

# API 配置
POLYMARKET_API_BASE_URL=https://gamma-api.polymarket.com
# POLYMARKET_API_KEY=your_key_here  # 可选 - 获取公共数据不需要

# 性能设置
POLYMARKET_CACHE_ENABLED=true
POLYMARKET_CACHE_TTL=60              # 缓存 TTL（秒）
POLYMARKET_RESOURCE_CACHE_TTL=300    # 资源缓存 TTL

# 日志
POLYMARKET_LOG_LEVEL=info            # trace, debug, info, warn, error
RUST_LOG=info                        # 替代日志级别设置

# 高级设置（很少需要）
POLYMARKET_API_TIMEOUT=30            # API 超时时间（秒）
POLYMARKET_API_MAX_RETRIES=3         # 重试次数
POLYMARKET_API_RETRY_DELAY=100       # 重试延迟（毫秒）

配置文件

或者，复制 config.toml.example 到 config.toml 并进行自定义：

[server]
name = "Polymarket MCP 服务器"
timeout_seconds = 30

[api]
base_url = "https://gamma-api.polymarket.com"
# api_key = "your_key_here"  # 可选
timeout_seconds = 30
max_retries = 3
retry_delay_ms = 100

[cache]
enabled = true
ttl_seconds = 60
max_entries = 1000
resource_cache_ttl_seconds = 300

[logging]
level = "info"
format = "pretty"
enable_colors = true

配置优先级

配置按以下顺序加载（从高到低优先级）：

1. 环境变量（例如，POLYMARKET_LOG_LEVEL=debug）
2. 配置文件（config.toml，polymarket-mcp.toml 等）
3. 内置默认值（生产就绪设置）

使用

Claude Desktop 集成

安装并配置 MCP 服务器后，您可以直接通过 Claude Desktop 与 Polymarket 数据交互。尝试这些示例提示：

🔍 市场发现：
- "显示前 10 个活跃预测市场"
- "搜索关于 'AI' 或 '人工智能' 的市场"
- "哪些是交易量最高的热门市场？"

📊 市场分析：
- "获取市场 ID 12345 的详细信息"
- "特朗普 2024 市场的当前价格是多少？"
- "分析关于加密货币市场的观点"

🤖 AI 驱动见解：
- "在选举市场中寻找套利机会"
- "给我总结前 5 个政治预测市场"
- "分析市场 67890 的交易机会"

示例使用流程

1. 询问 Claude："显示与 AI 相关的活跃预测市场"
2. Claude 使用：search_markets 工具，关键词 "AI"
3. 您得到：与 AI 相关市场的列表，包括价格和详细信息
4. 后续提问："分析流动性最强的 AI 市场"
5. Claude 使用：analyze_market 提示进行深入分析

开发与测试

# 快速测试（需要 Rust）
cargo run

# 启用调试日志
RUST_LOG=debug cargo run

# 运行所有测试
cargo test

# 检查代码质量
cargo clippy

# Docker 开发
docker build -t polymarket-mcp:latest .
docker run -it --rm -e RUST_LOG=debug polymarket-mcp:latest

# 手动测试 MCP 协议
echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}},"id":0}' | cargo run

MCP 协议实现

此服务器实现了完整的 MCP 规范，包含 5 个工具、3 个资源 和 3 个提示。

🔧 MCP 工具

工具	描述	参数
get_active_markets	获取当前活跃的预测市场	limit（可选，默认：50）
get_market_details	获取特定市场的详细信息	market_id（必需）
search_markets	通过关键词在问题/描述中搜索市场	keyword（必需），limit（可选，默认：20）
get_market_prices	获取市场的当前“是”/“否”价格	market_id（必需）
get_trending_markets	获取交易量最高的市场	limit（可选，默认：10）

📊 MCP 资源

Claude 可访问的自动刷新数据资源：

资源	描述	刷新频率
markets:active	当前活跃市场的列表	每 5 分钟
markets:trending	按交易量排序的市场	每 5 分钟
market:{id}	通过 ID 获取特定市场的详细信息	每 5 分钟

🤖 MCP 提示

AI 驱动的分析提示，提供智能市场见解：

提示	描述	参数
analyze_market	综合市场分析，包括交易见解	market_id（必需）
find_arbitrage	在相关市场中检测套利机会	keyword（必需），limit（可选，默认：10）
market_summary	概述顶级市场，并提供推荐	category（可选），limit（可选，默认：5）

API 文档

市场对象结构

{
  "id": "0x123...",
  "slug": "市场别名",
  "question": "X 是否会在 Y 日期发生？",
  "description": "详细的市场描述",
  "active": true,
  "closed": false,
  "liquidity": 50000.0,
  "volume": 125000.0,
  "end_date": "2024-12-31T23:59:59Z",
  "outcomes": ["是", "否"],
  "outcome_prices": ["0.65", "0.35"],
  "category": "政治"
}

错误处理

服务器实现了强大的错误处理机制：

• 网络错误：自动重试，带有指数退避和抖动
• 速率限制：对被速率限制的请求自动延迟
• 数据验证：所有 API 响应都经过验证和安全解析
• 缓存：防止冗余 API 调用，提高性能

开发

代码结构

src/
├── main.rs              # MCP 服务器实现和请求处理
├── lib.rs               # 库导出
├── config.rs            # 支持环境变量和文件的配置管理
├── models.rs            # 数据结构和 Polymarket API 类型
├── polymarket_client.rs # 带有缓存和重试逻辑的 HTTP 客户端
└── error.rs             # 错误类型和处理

实现的关键特性

• 干净架构：最小依赖，专注功能
• 类型安全性：全面使用 Rust 类型系统
• 性能：高效的缓存和 HTTP 连接池
• 可靠性：强大的错误处理和重试逻辑
• MCP 符合性：完全实现 MCP 协议规范

质量保证

此项目维护高标准的代码质量：

# 运行所有测试（总共 11 个测试）
cargo test

# 检查编译警告（应该是零）
cargo check

# 运行 clippy 检查（应该通过无警告）
cargo clippy --all-targets --all-features -- -D warnings -A clippy::pedantic

# 格式化代码
cargo fmt

# 构建优化的发布版
cargo build --release

当前状态：

• ✅ 零编译警告
• ✅ 所有测试通过（11/11）
• ✅ 干净的 clippy 检查
• ✅ 100% API 覆盖

依赖项

该项目使用少量、专注的依赖项：

# 核心 MCP 和异步运行时
rmcp = { git = "https://github.com/modelcontextprotocol/rust-sdk" }
tokio = { version = "1.0", features = ["rt-multi-thread", "macros", "sync", "time", "signal", "io-std"] }

# HTTP 客户端和序列化
reqwest = { version = "0.12", features = ["json", "gzip", "rustls-tls"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

# 配置和实用工具
config = "0.14"
dotenv = "0.15"
clap = { version = "4.0", features = ["derive"] }
fastrand = "2.0"  # 用于请求抖动

# 日期/时间和错误
chrono = { version = "0.4", features = ["serde"] }
anyhow = "1.0"
thiserror = "1.0"
uuid = { version = "1.0", features = ["v4"] }

# 日志
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

部署

Docker 部署

生产 Docker Compose

创建 docker-compose.yml：

version: '3.8'
services:
  polymarket-mcp:
    build: .
    image: polymarket-mcp:latest
    container_name: polymarket-mcp
    restart: unless-stopped
    environment:
      - RUST_LOG=info
      - POLYMARKET_CACHE_TTL=300
      - POLYMARKET_MAX_CONCURRENT_REQUESTS=10
    healthcheck:
      test: ["CMD", "polymarket-mcp", "--health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

# 使用 docker-compose 部署
docker-compose up -d

# 查看日志
docker-compose logs -f polymarket-mcp

# 更新并重启
docker-compose pull
docker-compose up -d

Systemd 服务（Linux）

对于 Linux 服务器，在 /etc/systemd/system/polymarket-mcp.service 创建：

[Unit]
Description=Polymarket MCP 服务器
After=network.target

[Service]
Type=simple
User=polymarket
ExecStart=/usr/local/bin/polymarket-mcp
Restart=always
RestartSec=10
Environment=RUST_LOG=info
EnvironmentFile=/etc/polymarket-mcp/.env

[Install]
WantedBy=multi-user.target

故障排除

常见问题

服务器无法启动

检查步骤：

1. 验证二进制路径：ls -la /path/to/target/release/polymarket-mcp
2. 测试二进制文件：./target/release/polymarket-mcp --help
3. 检查配置：RUST_LOG=debug cargo run

MCP 连接问题

故障排查：

1. 验证 claude_desktop_config.json 语法是否为有效 JSON
2. 检查配置中的二进制绝对路径
3. 配置更改后重启 Claude Desktop
4. 检查 Claude Desktop 日志：~/Library/Logs/Claude/mcp.log（macOS）

API 错误

常见解决方案：

• 验证互联网连接
• 检查 API 端点可用性
• 确保没有速率限制（内置自动处理）
• 查看错误日志：RUST_LOG=debug

调试模式

启用调试日志以获得详细输出：

{
  "mcpServers": {
    "polymarket": {
      "command": "/path/to/polymarket-mcp/target/release/polymarket-mcp",
      "env": {
        "RUST_LOG": "debug"
      }
    }
  }
}

日志位置

• Claude Desktop MCP 日志：~/Library/Logs/Claude/mcp.log（macOS）
• Claude Desktop 主日志：~/Library/Logs/Claude/main.log（macOS）
• 服务器输出：所有日志均输出到 stderr，可见于 Claude Desktop MCP 日志

性能

服务器进行了性能优化：

• 缓存：