MCP-Pionex

Сервер MCP (Model Context Protocol) для биржи Pionex, построенный на библиотеке pionex_py. Предоставляет данные рынка, аккаунта, спот-торговли, grid-ботов и Dual Investment как инструменты MCP, со строгим уровнем защиты от галлюцинаций: ИИ не может выдумывать символы, цены, параметры или выполнять что-либо без проверки в реальном времени и двухфазного подтверждения.

Работает с Claude Code / Claude Desktop и с локальными LLM (LM Studio, Ollama через mcphost или встроенный мост). Полное руководство в docs/GUIA.md.

Возможности

• 43 инструмента в 7 группах: meta, рынок (публичный), технический анализ (EMAs, RSI, MACD, FVG, order blocks, структура), аккаунт, trading, боты, earn.

• Только чтение по умолчанию — trading, боты и earn отключены, пока оператор не включит их через переменную окружения.

• Двухфазный коммит — любое действие, изменяющее состояние (prepare_* → confirm_action), требует одноразовый токен, криптографически привязанный к проверенным параметрам и с истечением срока действия.

• Проверка символов в реальном времени — пара, которой не существует на Pionex, никогда не попадает в API.

• Жёсткие лимиты — максимальный номинал на ордер, максимальное отклонение лимитной цены от текущей цены, опциональный whitelist символов.

• Конверты происхождения — каждый ответ содержит исходный endpoint, UTC timestamp и метку computed для производных значений.

• Дословные ошибки — ошибки API Pionex возвращаются с исходным кодом и сообщением, никогда не перефразируются.

• Журнал аудита — каждый prepare/confirm/cancel сохраняется в локальный JSONL.

Related MCP server: okx-trade-mcp

Требования

• Python ≥ 3.11

• uv (рекомендуется) или pip

• API-ключ Pionex (только для инструментов аккаунта/trading; данные рынка не требуют его)

pionex_py и SDK mcp устанавливаются автоматически из PyPI.

Установка

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

Конфигурация

Всё управляется переменными окружения (см. .env.example):

Лимиты устанавливает человек-оператор: разговор с ИИ не может их повысить или отключить.

Регистрация в 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")

Если trading отключён, prepare_order отвечает точным сообщением о том, какую переменную окружения должен включить оператор.

Как предотвращает галлюцинации

1. Закрытые словари: side, order_type, interval, market_type, grid_type, product_type проверяются по whitelist'ам, повторяющим официальную документацию Pionex; выдуманное значение возвращает полный список допустимых значений.

2. Символы проверяются в реальном времени через GET /api/v1/common/symbols (кэш 10 мин), с предложениями исправления (BTCUSDT → «возможно, вы имели в виду BTC_USDT?»).

3. Две фазы с токеном, привязанным к параметрам: токен содержит SHA-256 хэш действия и его параметров; при подтверждении выполняются параметры, хранящиеся на сервере, а не те, которые передаёт ИИ.

4. Числовые ограничители оператора: максимальный номинал и отклонение цены проверяются по живым данным биржи.

5. Обязательное происхождение: ИИ получает инструкцию (в 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 "¿a cuánto está el BTC?" — полный агентный цикл против Ollama с 43 инструментами.

С локальными моделями держите PIONEX_MCP_TRADING_ENABLED=false, кроме случаев пристального наблюдения: ограничители сервера те же, но маленькие модели галлюцинируют чаще.

Документация

• docs/GUIA.md — полное руководство: установка, конфигурация, интеграции (Claude и локальная LLM), потоки, операционная безопасность, устранение неполадок и расширение.

• docs/INFORME.md — отчёт о возможностях и проверке.

• CLAUDE.md — внутреннее руководство проекта для ИИ-агентов.

• Официальная документация API: https://pionex-doc.gitbook.io/apidocs/

Лицензия

MIT