MCP-Pionex

面向 Pionex 交易所的 MCP（模型上下文协议） 服务器，基于 pionex_py 库构建。它将市场数据、账户、现货交易、网格机器人和双币投资作为 MCP 工具暴露，并带有严格的反幻觉安全层：AI 无法凭空捏造交易对、价格、参数，也无法在未经实时验证和两阶段确认的情况下执行任何操作。

可与 Claude Code / Claude Desktop 以及本地 LLM（LM Studio、通过 mcphost 或内置桥接使用 Ollama）配合使用。完整指南见 docs/GUIA.md。

特性

• 43 个工具，分为 7 组：元信息、市场（公开）、技术分析（EMA、RSI、MACD、FVG、订单块、结构）、账户、交易、机器人、理财。

• 默认只读 —— 交易、机器人和理财在操作者通过环境变量启用之前均处于禁用状态。

• 两阶段提交 —— 所有改变状态的操作（prepare_* → confirm_action）都需要一次性令牌，该令牌与已验证参数进行加密绑定，并设有过期时间。

• 实时交易对验证 —— 在 Pionex 上不存在的交易对永远不会到达 API。

• 硬性限制 —— 单笔订单的名义金额上限、限价单价格与实时价格的最大偏差、可选的交易对白名单。

• 来源信封 —— 每个响应都带有来源端点、UTC 时间戳，以及针对派生值的 computed 标记。

• 字面错误 —— Pionex API 的错误以其原始代码和消息返回，绝不转述。

• 审计日志 —— 每次 prepare/confirm/cancel 都会记录在本地 JSONL 文件中。

Related MCP server: okx-trade-mcp

要求

• Python ≥ 3.11

• uv（推荐）或 pip

• Pionex API 密钥（仅账户/交易工具需要；市场数据不需要）

pionex_py 和 mcp SDK 会自动从 PyPI 安装。

安装

git clone https://github.com/alejandrorodm/MCP-Pionex
cd MCP-Pionex
uv sync

配置

所有内容均通过环境变量控制（参见 .env.example）：

限制由人类操作者设定：与 AI 的对话无法提高或禁用这些限制。

在 Claude Code 中注册

claude mcp add pionex \
  --env PIONEX_API_KEY=tu_key \
  --env PIONEX_API_SECRET=tu_secret \
  -- uv --directory /home/zoiyo/repos/mcp_pionex_py run mcp-pionex

或在 .mcp.json / claude_desktop_config.json 中：

{
  "mcpServers": {
    "pionex": {
      "command": "uv",
      "args": ["--directory", "/home/zoiyo/repos/mcp_pionex_py", "run", "mcp-pionex"],
      "env": {
        "PIONEX_API_KEY": "tu_key",
        "PIONEX_API_SECRET": "tu_secret",
        "PIONEX_MCP_TRADING_ENABLED": "false"
      }
    }
  }
}

典型用法

Usuario: ¿a cuánto está el BTC?
IA → get_price("BTC_USDT")            # precio vivo, nunca de memoria

Usuario: compra 20 USDT de ETH
IA → prepare_order(symbol="ETH_USDT", side="BUY", order_type="MARKET", amount="20")
     → muestra el resumen y el token al usuario
Usuario: confirmo
IA → confirm_action(confirmation_token="ab12cd34ef56-9f3a")

如果交易被禁用，prepare_order 会返回确切消息，说明操作者需要启用哪个环境变量。

如何避免幻觉

1. 封闭词汇表：side、order_type、interval、market_type、grid_type、product_type 会对照复制 Pionex 官方文档的白名单进行验证；虚构的值会返回完整的有效值列表。

2. 实时验证交易对：对照 GET /api/v1/common/symbols（缓存 10 分钟）进行验证，并带有纠错建议（BTCUSDT → 「您是不是想输入 BTC_USDT？」）。

3. 两阶段 + 参数绑定令牌：令牌包含操作及其参数的 SHA-256 哈希；确认时执行的是存储在服务器上的参数，而非 AI 传入的参数。

4. 操作者数值守卫：名义金额上限和价格偏差会对照交易所的实时数据进行校验。

5. 强制来源标注：AI 收到指令（在服务器 instructions 和每个信封中）只能报告 data 中存在的字段。

6. 逐字错误 + 所有已准备和已执行操作的 JSONL 审计。

结构

src/mcp_pionex/
├── server.py      # FastMCP, instructions anti-alucinación, tools meta
├── config.py      # Settings por entorno (conservador por defecto)
├── safety.py      # vocabularios, verificación de símbolos, 2-fases, límites, audit
├── client.py      # singletons perezosos de los clientes pionex_py
├── actions.py     # registro de ejecutores para confirm_action
└── tools/
    ├── market.py   # 9 tools públicas de mercado
    ├── account.py  # 8 tools de cuenta (solo lectura)
    ├── trading.py  # 6 tools de trading (2 fases)
    ├── bots.py     # 6 tools de bots
    └── earn.py     # 7 tools de Dual Investment

与本地 LLM 配合使用

三种方式（详见 docs/GUIA.md）：

• LM Studio：原生支持 MCP —— 将相同的 mcpServers 块粘贴到其 mcp.json 中。

• Ollama + mcphost：mcphost -m ollama:qwen3 --config mcp.json。

• 内置桥接：uv run examples/ollama_bridge.py "BTC 现在多少钱？" —— 使用全部 43 个工具对 Ollama 进行完整的智能体循环。

使用本地模型时，除非有密切监督，否则请保持 PIONEX_MCP_TRADING_ENABLED=false：服务器守卫是相同的，但小型模型更容易产生幻觉。

文档

• docs/GUIA.md —— 完整指南：安装、配置、集成（Claude 和本地 LLM）、流程、操作安全、故障排除和扩展。

• docs/INFORME.md —— 能力与验证报告。

• CLAUDE.md —— 面向 AI 代理的项目内部指南。

• API 官方文档：https://pionex-doc.gitbook.io/apidocs/

许可证

MIT