MCP-Pionex

MCP-Server (Model Context Protocol) für die Börse Pionex, entwickelt auf Grundlage der Bibliothek pionex_py. Er stellt Marktdaten, Konto, Spot-Trading, Grid-Bots und Dual Investment als MCP-Tools bereit, mit einer strengen Sicherheitsschicht gegen Halluzinationen: Die KI kann keine Symbole, Preise oder Parameter erfinden und nichts ohne Live-Validierung und zweiphasige Bestätigung ausführen.

Funktioniert mit Claude Code / Claude Desktop und mit lokalen LLMs (LM Studio, Ollama über mcphost oder die enthaltene Bridge). Vollständiger Leitfaden in docs/GUIA.md.

Funktionen

• 43 Werkzeuge in 7 Gruppen: Meta, Markt (öffentlich), technische Analyse (EMAs, RSI, MACD, FVG, Order Blocks, Struktur), Konto, Trading, Bots, Earn.

• Standardmäßig nur-lesend – Trading, Bots und Earn sind deaktiviert, bis der Betreiber sie über eine Umgebungsvariable aktiviert.

• Zwei-Phasen-Commit – jede zustandsändernde Aktion (prepare_* → confirm_action) erfordert ein Einmal-Token, das kryptografisch an die validierten Parameter gebunden ist und abläuft.

• Live-Symbolprüfung – ein Paar, das es bei Pionex nicht gibt, gelangt nie an die API.

• Strikte Grenzen – Maximalbetrag pro Order, maximale Abweichung eines Limit-Preises gegenüber dem Live-Preis, optionale Symbol-Whitelist.

• Herkunftsnachweise – jede Antwort enthält den Ursprungs-Endpunkt, den UTC-Zeitstempel und die Kennzeichnung computed für abgeleitete Werte.

• Wörtliche Fehler – Fehler der Pionex-API werden mit ihrem ursprünglichen Code und ihrer ursprünglichen Meldung zurückgegeben, niemals paraphrasiert.

• Audit-Log – jede Aktion (prepare/confirm/cancel) wird in einem lokalen JSONL-Log aufgezeichnet.

Related MCP server: okx-trade-mcp

Voraussetzungen

• Python ≥ 3.11

• uv (empfohlen) oder pip

• Ein Pionex-API-Schlüssel (nur für Konto-/Trading-Werkzeuge; Marktdaten benötigen keinen)

pionex_py und das mcp-SDK werden automatisch aus PyPI installiert.

Installation

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

Konfiguration

Alles wird über Umgebungsvariablen gesteuert (siehe .env.example):

Die Grenzen legt der menschliche Betreiber fest: Das Gespräch mit der KI kann sie weder erhöhen noch deaktivieren.

Registrierung in 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

Oder in .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"
      }
    }
  }
}

Typische Verwendung

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")

Wenn Trading deaktiviert ist, antwortet prepare_order mit der genauen Meldung, welche Umgebungsvariable der Betreiber aktivieren muss.

Wie Halluzinationen verhindert werden

1. Geschlossene Vokabulare: side, order_type, interval, market_type, grid_type, product_type werden gegen Whitelists validiert, die die offizielle Pionex-Dokumentation abbilden. Ein erfundenes Wert gibt die vollständige Liste der gültigen Werte zurück.

2. Live-verifizierte Symbole gegen GET /api/v1/common/symbols (Cache: 10 Minuten), mit Korrekturvorschlägen (BTCUSDT → „meintest du BTC_USDT »).

3. Möchten Sie einen Parameter-Token: Das Token enthält einen SHA-256-Hash der Aktion und ihrer Parameter. Bei der Bestätigung werden die auf dem Server gespeicherten Parameter ausgeführt, nicht diejenige, die die KI übergibt.

4. Numerische Schutzmechanismen des Betreibers: Maximaler Notionalwert und Preisabweichung werden gegen Live-Daten der Börse geprüft.

5. Vorgeschriebene Herkunftsangabe: Die KI erhält die Aufforderung (in den instructions des Servers und in jedem Envelope), nur die Felder wiederzugeben, die in data vorhanden Gibt es.

6. Wörtliche Fehler + JSONL-Audit von allem Vorbereiteten und Ausgeführten.

Struktur

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

Verwendung mit einem lokalen LLM

Drei Wege (Details in docs/GUIA.md):

• LM Studio: Unterstützt MCP nativ – füge denselben mcpServers-Block in dessen mcp.json ein.

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

• Integrierte Brücke: uv run examples/ollama_bridge.py "¿a cuánto está el BTC?" – vollständige agentische Schleife mit Ollama und allen 43 Werkzeugen.

Bei lokale Modellenelemmeße: Lasse PIONEX_MCP_TRADING_ENABLED=false, außer wenn die Ausführung sehr eng überwacht wird: Die Schutzmechanismen des Servers sind dieselben, aber die kleinen Modelle halluzinieren – eher mehr.

Dokumentation

• docs/GIIT.md – vollständiger Leitfaden: Installation, Konfiguration, Integrationen (Claude und lokale LLM), Abläufe, Betriebssicherheit, Fehlerbehebung und Erweiterung.

• docs/INFORME.md – Bericht zu Funktionsumfang und Überprüfung.

• CLAUDE.md – interner Projektleitfaden für KI-Agenten.

• Offizielle API-Dokumentation: https://pionex-doc.gitbook.io/apidocs/

Lizenz

MIT