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, 오더 블록, 구조), 계정, 거래, 봇, earn.

• 기본적으로 읽기 전용 — 운영자가 환경 변수로 활성화할 때까지 거래, 봇, earn은 비활성화됩니다.

• 2단계 커밋 — 상태를 변경하는 모든 작업(prepare_* → confirm_action)은 검증된 파라미터에 암호학적으로 바인딩되고 만료 시간이 있는 일회용 토큰이 필요합니다.

• 실시간 심볼 검증 — Pionex에 존재하지 않는 페어는 절대 API에 도달하지 않습니다.

• 하드 한도 — 주문당 명목 한도, 실시간 가격 대비 LIMIT 가격의 최대 편차, 선택적 심볼 화이트리스트.

• 출처 봉투 — 각 응답에는 출처 엔드포인트, 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는(서버 지침과 각 봉투에서) 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?" — 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