polymarket-mcp

Polymarket MCP

向 AI Agent 提供只读 Polymarket 预测市场数据的 MCP 服务。工具封装了 Polymarket 的公开 Gamma（市场发现）和 Data（持仓、投资组合、排行榜）API。此服务未集成 CLOB，无法下单交易或读取订单簿。

工具

工具	描述
search_markets	按标题或描述搜索市场
get_market_details	获取单个市场的完整详情（通过 slug 或 Polymarket URL）
get_trending_markets	按交易量、流动性或竞争程度排序的热门事件
get_market_holders	获取某个市场各结果的顶级持有者（通过 condition ID、slug 或 URL）
get_leaderboard	按盈亏或交易量排序的顶级交易者
get_user_positions	获取某个钱包地址的未平仓持仓
get_user_performance	获取某个钱包的投资组合价值、盈亏、交易量和排行榜名次

所有工具均返回适合 Agent 使用的 Markdown 格式内容。无需 API 密钥或钱包签名。

资源

静态参考上下文（不调用 API）。可在 MCP 客户端中附加，或通过 Inspector 阅读。

URI	描述
polymarket://glossary	事件、市场、slug、conditionId 和钱包术语
polymarket://categories	排行榜类别、时间段和标签 slug
polymarket://tool-guide	各工具的适用场景及工具串联工作流

提示词

由用户触发、用于编排工具的工作流模板：

提示词	描述
research_market	市场详情 → 持有者 → 研究摘要（slug 或 market_link）
compare_traders	并排比较两个钱包的表现和持仓
scan_trending	扫描热门事件，可选使用 tag_slug 和 limit

要求

• Python 3.12+
• uv（推荐）或 Docker
• Node.js（可选，仅用于 MCP Inspector）

快速开始

此服务使用 http://127.0.0.1:8000/mcp 上的 streamable HTTP。请先启动服务，再将 MCP 客户端连接到该 URL。

git clone https://github.com/0xChron/polymarket-mcp.git
cd polymarket-mcp
uv sync
uv run polymarket-mcp

在 Windows 上，可在 PowerShell、Command Prompt 或 Git Bash 中运行相同命令。MCP 客户端保持连接期间，请勿关闭终端。

Docker

安装 Docker Desktop 后，所有平台上的操作方式相同：

git clone https://github.com/0xChron/polymarket-mcp.git
cd polymarket-mcp
docker build -t polymarket-mcp .
docker run --rm -p 8000:8000 -e FASTMCP_HOST=0.0.0.0 polymarket-mcp

FASTMCP_HOST=0.0.0.0 可让服务接受来自容器外部的连接。

验证服务

在另一个终端中打开 MCP Inspector：

npx -y @modelcontextprotocol/inspector

使用 Streamable HTTP 传输方式连接到 http://localhost:8000/mcp。

从 MCP 客户端连接

此服务使用 streamable-http 传输方式（而非 stdio）。请先启动服务（参见快速开始），然后将以下配置添加到 MCP 客户端。

Claude Desktop

前往 Claude → Settings → Developer → Edit Config，打开 claude_desktop_config.json，然后加入以下内容：

{
  "mcpServers": {
    "polymarket": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

如果已配置其他 MCP 服务，请将 "polymarket" 条目添加到现有的 mcpServers 对象中，而不是替换整个文件。

如需手动编辑，配置文件位置如下：

平台	路径
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

保存文件后，完全退出并重启 Claude Desktop。开始新的聊天前，必须先在终端中运行此服务。

Cursor

前往 Settings → Tools & MCP → New MCP Server，打开 ~/.cursor/mcp.json（Windows：%USERPROFILE%\.cursor\mcp.json），然后添加相同的 polymarket 条目：

{
  "mcpServers": {
    "polymarket": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

保存后重启 Cursor。

Agent 提示词示例

连接后，Agent 可以自然地调用工具：

• “搜索 Polymarket 上有关比特币 ETF 的活跃市场”
• “现在有哪些热门市场？”
• “特朗普选举市场的顶级持有者是谁？”
• “显示加密货币交易者的历史盈亏排行榜”
• “获取 https://polymarket.com/event/will-bitcoin-hit-100k 的详情”
• “显示钱包 0x… 的未平仓头寸”
• “0x… 的历史盈亏和排行榜名次是多少？”

在 MCP Inspector 中，试试 Prompts 标签页（例如 research_market），或查看 Resources 中的术语表和工具指南。

配置

可选环境变量可覆盖 API 端点和服务设置。

macOS / Linux / Git Bash

export FASTMCP_HOST=0.0.0.0
export FASTMCP_PORT=8000
uv run polymarket-mcp

Windows (PowerShell)

$env:FASTMCP_HOST = "0.0.0.0"
$env:FASTMCP_PORT = "8000"
uv run polymarket-mcp

变量	默认值	说明
GAMMA_URL	https://gamma-api.polymarket.com	Gamma API 基础 URL
DATA_URL	https://data-api.polymarket.com	Data API 基础 URL
DEFAULT_TIMEOUT	15	HTTP 请求超时（秒）
FASTMCP_HOST	127.0.0.1	绑定地址（Docker 使用 0.0.0.0）
FASTMCP_PORT	8000	监听端口

开发

uv run polymarket-mcp          # Start the server
uv run pytest                  # Run tests
npx -y @modelcontextprotocol/inspector   # Open MCP Inspector
docker build -t polymarket-mcp .         # Build Docker image

在 macOS/Linux 上，Makefile 中的 make run、make test 等快捷命令会调用相同的命令。

有关架构、约定以及如何添加新工具的信息，请参阅 docs/PROJECT_KNOWLEDGE_BASE.md。

许可证

MIT — 详见 LICENSE。