graph-polymarket-mcp

graph-polymarket-mcp

已以 io.github.PaulieB14/graph-polymarket-mcp 发布至 MCP Registry

前提条件

你需要一个免费的 Graph API 密钥（约需 2 分钟）：

1. 前往 The Graph Studio
2. 连接你的钱包（MetaMask、WalletConnect 等）
3. 点击侧边栏中的 “API Keys” 并创建一个密钥
4. 免费套餐每月包含 100,000 次查询

安装

npm install -g graph-polymarket-mcp

或使用 npx 直接运行：

npx graph-polymarket-mcp

配置

Claude Desktop

将以下内容添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "graph-polymarket": {
      "command": "npx",
      "args": ["-y", "graph-polymarket-mcp"],
      "env": {
        "GRAPH_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code

claude mcp add graph-polymarket -- npx -y graph-polymarket-mcp

运行前设置环境变量 GRAPH_API_KEY。

Cursor / 其他 MCP 客户端

使用 stdio 传输，将 npx graph-polymarket-mcp 作为命令，并将 GRAPH_API_KEY 作为环境变量传入。

OpenClaw / 远程 Agent（SSE）

SSE 传输没有身份验证。 任何可以访问该端口的人都能调用所有工具， 而这些调用会消耗你的 GRAPH_API_KEY 配额。--http 会在容器内绑定到 0.0.0.0， 因此请在主机上将其发布到 127.0.0.1，并在任何可从主机外部访问的端口前配置带 TLS 和身份验证的反向代理。 对于本地 Agent，建议使用默认的 stdio 传输——它完全不暴露网络。

使用 HTTP 传输启动服务：

# Dual transport — stdio + SSE on port 3851
GRAPH_API_KEY=your-key npx graph-polymarket-mcp --http

# SSE only (for remote/server deployments)
GRAPH_API_KEY=your-key npx graph-polymarket-mcp --http-only

# Custom port
MCP_HTTP_PORT=4000 GRAPH_API_KEY=your-key npx graph-polymarket-mcp --http

然后将 Agent 指向 SSE 端点：

{
  "mcpServers": {
    "graph-polymarket": {
      "url": "http://localhost:3851/sse"
    }
  }
}

传输模式

调用方式	传输方式	使用场景
npx graph-polymarket-mcp	stdio	Claude Desktop、Cursor、Claude Code
npx graph-polymarket-mcp --http	stdio + SSE :3851	双模式——本地和远程 Agent
npx graph-polymarket-mcp --http-only	SSE :3851	OpenClaw、远程部署

启用 HTTP 传输时，可通过 http://localhost:3851/health 访问 /health 端点。

可用工具

核心工具

工具	描述
list_subgraphs	列出所有可用的 Polymarket 子图及其描述和关键实体
get_subgraph_schema	获取指定子图的完整 GraphQL 架构
query_subgraph	对任意子图执行自定义 GraphQL 查询

特定领域工具

工具	描述	子图
get_market_data	获取市场／条件数据，包括结果和结算状态	Main
get_global_stats	获取平台统计数据：市场数量 + 实际交易量／费用／交易笔数	Main + Orderbook
get_account_pnl	获取交易者的盈亏和绩效指标（胜率、利润因子、最大回撤）	Beefy P&L
get_top_traders	按盈亏、胜率、交易量或利润因子排序的排行榜。交叉比对 Orderbook，标记 OB 交易量高于 Beefy 跟踪交易量的行，并列出排行榜中缺失的仅在 OB 中出现的交易者。	Beefy P&L + Orderbook
get_daily_stats	每日交易量、费用、交易者数量和市场活动（1–90 天）	Beefy P&L
get_market_positions	特定结果代币的最大持有者及其盈亏	Beefy P&L
get_user_positions	当前代币持仓。交叉比对 Orderbook：当 totalBought=0 但存在 OB 交易量时，标记 ⚠ 仅在订单簿中出现的条目；当 OB 交易量 > 2× 拆分抵押品时，标记 ⚠ 混合条目。	Slimmed P&L + Orderbook
get_recent_activity	按时间顺序整合拆分、合并、赎回和订单簿成交的活动流。支持按地址筛选。	Activity + Orderbook
get_orderbook_trades	获取近期订单成交，并按挂单方／吃单方筛选	Orderbook
get_market_open_interest	按未平仓持仓中的 USDC 锁定量排列的热门市场。交叉比对 Main 子图，标记已结算市场中的 ⚠ 死钱 OI（无法在链上赎回的亏损方代币）。	Open Interest + Main
get_oi_history	特定市场的每小时 OI 快照（用于绘制趋势图）	Open Interest
get_global_open_interest	全平台未平仓总量和市场数量	Open Interest
get_market_resolution	UMA 预言机结算状态，支持按状态筛选	Resolution
get_disputed_markets	预言机结算期间遭到争议的市场（高信号事件）	Resolution
get_market_revisions	对市场结算的版主干预和更新	Resolution
get_trader_profile	综合 CTF 事件、USDC 流向和 Orderbook 成交，提供完整交易者档案。将钱包分类为混合型／仅订单簿／仅拆分抵押品，并在盈亏子图不可靠时发出警告。	Traders + Orderbook
get_trader_usdc_flows	USDC 存取款历史，支持按方向筛选	Traders

Polymarket REST API 工具（无需 Graph API 密钥）

工具	描述	API
search_markets	按文本查询搜索市场，并使用筛选条件（活跃、已关闭、按交易量／流动性排序）	Gamma
get_market_info	按 slug 或条件 ID 获取详细市场元数据	Gamma
list_polymarket_events	浏览事件（相关市场的分组），支持按标签／状态筛选	Gamma
get_polymarket_event	获取单个事件及其所有相关市场	Gamma
get_live_prices	获取结果代币的实时 CLOB 价格（买入／卖出，单个或批量）	CLOB
get_live_spread	买卖价差 + 中间价，用于评估市场流动性	CLOB
get_live_orderbook	获取代币的完整订单簿（所有挂单买价和卖价）	CLOB
get_price_history	历史价格时间序列（从 1m 到最大间隔，可配置精度）	CLOB
get_last_trade	获取结果代币的最近成交价	CLOB
get_clob_market	CLOB 市场详情：代币 ID、实时价格、最小订单量／报价单位	CLOB
search_markets_enriched	强大工具：一次调用即可搜索并自动补充实时 CLOB 价格和链上结算状态	Gamma + CLOB + Graph

CLOB V2 工具

Polymarket 于 2026-04-28 迁移到 V2 交易所合约。这些工具读取 V2 子图， 其索引从区块 84902353 开始，不包含迁移前的历史数据——V1 和 V2 属于不同 时期，并非新旧版本。

工具	描述	子图
get_builder_leaderboard	按路由交易量、订单数或费用对 V2 构建者排名，并显示每位构建者在 V2 交易量中的占比。V1 中没有对应工具——V1 合约从未发出过构建者代码	V2 Orderbook
get_builder_activity	某个构建者代码路由的近期成交，以及该构建者的汇总数据	V2 Orderbook
get_v2_top_traders	V2 顶级真实交易者，并过滤掉交易所合约	V2 Orderbook
check_subgraph_freshness	通过子图 _meta 区块实时读取任意子图落后于链头的程度	任意

构建者归因是 V2 新增的能力。每笔 V2 成交都带有路由该笔交易的前端、机器人或集成方的 builder 代码，因此“究竟是谁在路由这些交易”成为了一个可以回答的问题——截至 2026-08-08，共有 3,325 个构建者。

这两个工具会帮你避开两个陷阱。 V2 交易所合约会显示为 Account 行，因为订单簿中的订单撮合时，交易所是 taker——如果直接对账户排名，0xe111…996b（176M 笔成交）和 0xe222…0f59（41M 笔成交）会排在人类交易者之前。get_v2_top_traders 会将它们排除。信任某个数字之前，check_subgraph_freshness 会报告任意子图的头区块。

数据来源

The Graph 子图（需要 GRAPH_API_KEY）

链上索引数据——历史分析、盈亏、未平仓量和结算状态的权威数据来源。

子图

CLOB V2 — 主要版本（从区块 84902353 开始）

名称	IPFS 哈希	状态	描述
V2 Main	QmTKrqyYg23BjhihmsrRjbV9cVS2piNmnHsr7cjYaTgdWu	与链头同步	条件、结算状态和计数器（市场工具的默认子图）
V2 Orderbook	QmNtJGxpAjFgoHhMwdijyvbLrpPPiHHX2qct56nTpk42Bs	与链头同步	带有构建者代码归因的 V2 成交
V2 P&L	QmT21E4p8r6FCzW2EPK4NVj1dbcggdvKxZr8uuMcB4P5Cu	与链头同步	仅基于 V2 成交的成本基础和已实现盈亏
Open Interest V2	QmbT2MmS2VGbGihiTUmWk6GMc2QYqoT9ZhiupUicYMWt6H	⚠️ 未分配索引器（2026-10-15）	按市场和全局统计的未平仓量，包含每小时快照

状态于 2026-10-15 通过 _meta 验证。

V1 — 旧版（2026-04-28 迁移前的历史数据）

名称	IPFS 哈希	描述
Main (legacy)	QmdyCguLEisTtQFveEkvMhTH7UzjyhnrF9kpvhYeG4QX8a	所有时期的条件，包括迁移前数据；传入 subgraph: "main"
Beefy P&L	QmbHwcGkumWdyTK2jYWXV3vX4WyinftEGbuwi7hDkhPWqG	全面的盈亏跟踪
Slimmed P&L	QmZAYiMeZiWC7ZjdWepek7hy1jbcW3ngimBF9ibTiTtwQU	精简的位置数据
Activity	Qmf3qPUsfQ8et6E3QNBmuXXKqUJi91mo5zbsaTkQrSnMAP	仓位管理事件
Orderbook	QmVGA9vvNZtEquVzDpw8wnTFDxVjB6mavTRMTrKuUBhi4t	订单成交分析（全时期交易量）
Resolution	QmZnnrHWCB1Mb8dxxXDxfComjNdaGyRC66W8derjn3XDPg	UMA 预言机结算生命周期
Traders	QmfT4YQwFfAi77hrC2JH3JiPF7C4nEn27UQRGNpSpUupqn	按交易者划分的事件日志和 USDC 流向

Open Interest 已经是一个 V2 部署；它读取 ConditionalTokens，而 V2 并未更改该合约，因此不存在迁移造成的数据中断。

应查询哪个时期：所有时期或 2026-04-28 之前 → V1。 迁移后的活动，或任何与构建者有关的内容 → V2。beefy_pnl 保留了 V2 P&L 不具备的对冲基金指标（winRate、profitFactor、maxDrawdown、daily series），因此交易者质量评分仍使用 V1。

示例查询

连接后，AI Agent 可以：

市场发现（Gamma API）

• “搜索与 AI 有关的预测市场”
• “显示当前最活跃的 Polymarket 事件”
• “查找与 2024 年选举有关的市场，并按交易量排序”
• “‘crypto’ 类别中有哪些市场？”

实时交易数据（CLOB API）

• “Trump YES 代币的当前价格是多少？”
• “显示这个市场的完整订单簿”
• “这个代币的买卖价差是多少？”
• “显示这个市场过去一周的价格历史”

链上分析（The Graph）

• “Polymarket 当前的全局统计数据是什么？”
• “显示最近的 20 笔订单簿交易”
• “地址 0x... 的持仓是什么？”（如果钱包仅通过 OB 买入建仓，则会标记）
• “交易者 0x... 的盈亏是多少？”
• “目前哪些市场的未平仓量最高？”（会标记已结算市场中的沉淀资金未平仓量）
• “显示 Polymarket 上有争议的市场”
• “排名靠前的交易者有哪些？”（会标记 Beefy 盈亏未涵盖的 OB 交易量）
• “显示钱包 0x... 的完整交易历史”（包括 OB 成交和建仓类型分类）

开发

git clone https://github.com/PaulieB14/graph-polymarket-mcp.git
cd graph-polymarket-mcp
npm install
npm run build
GRAPH_API_KEY=your-key node build/index.js

许可证

MIT