MCP-Pionex

Pionex 取引所向けの MCP（Model Context Protocol） サーバー。ライブラリ pionex_py 上に構築されています。マーケットデータ、アカウント、スポット取引、グリッドボット、Dual Investment を MCP ツールとして公開し、厳格な幻覚（ハルシネーション）防止セキュリティ層を備えています。AI はシンボル、価格、パラメータを捏造できず、ライブ検証と2フェーズ確認なしには何も実行できません。

Claude Code / Claude Desktop および ローカルLLM（LM Studio、mcphost 経由の Ollama、または同梱ブリッジ）で動作します。完全なガイドは docs/GUIA.md にあります。

特徴

• 7グループ43ツール: メタ、マーケット（公開）、テクニカル分析（EMA、RSI、MACD、FVG、オーダーブロック、構造）、アカウント、取引、ボット、アーン。

• デフォルトで読み取り専用 — 取引、ボット、アーンは、オペレーターが環境変数で有効化するまで無効です。

• 2フェーズコミット — 状態を変更するすべてのアクション（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. パラメータに紐づいたトークンによる2フェーズ: トークンにはアクションとそのパラメータの 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での使用

3つの方法（詳細は docs/GUIA.md）:

• LM Studio: MCP をネイティブサポート — 同じ mcpServers ブロックを mcp.json に貼り付けます。

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

• 同梱ブリッジ: uv run examples/ollama_bridge.py "¿a cuánto está el 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