Luno MCP Server

Ein Model Context Protocol (MCP)-Server für die Luno-API für den Kryptowährungshandel. Dieser Server bietet eine standardisierte Schnittstelle für KI-Modelle und -Anwendungen zur Interaktion mit der Luno-API für den Kryptowährungshandel.

 _                        __  __  ____ ____   
| |    _   _ _ __   ___  |  \/  |/ ___|  _ \  
| |   | | | | '_ \ / _ \ | |\/| | |   | |_) | 
| |___| |_| | | | | (_) || |  | | |___|  __/  
|_____|\__,_|_| |_|\___/ |_|  |_|\____|_|     

Merkmale

Echtzeit-Preisinformationen zu Kryptowährungen über die Luno-API
Marktübersicht für alle Handelspaare
Kontostandsabfragen
Auftragsverwaltung (Aufgeben, Stornieren, Status)
Abrufen des Transaktionsverlaufs
Gebühreninformationen
Standardisierte JSON-RPC 2.0-Schnittstelle
Einfache Integration mit KI-Anwendungen

Voraussetzungen

Python 3.8+ (Python 3.9+ empfohlen)
uv für die Paketverwaltung
Luno-Konto mit API-Schlüsseln (für volle Funktionalität)

Installation

Dieses Repository klonen

git clone https://github.com/amanasmuei/mcp-luno.git
cd mcp-luno

Erstellen Sie eine virtuelle Umgebung mit uv

uv venv
source .venv/bin/activate  # On macOS/Linux
# On Windows use: .venv\Scripts\activate

Abhängigkeiten installieren

uv pip install -r requirements.txt

Konfigurieren Sie Ihre Luno-API-Anmeldeinformationen (wählen Sie eine Methode):

Docker-Unterstützung

Sie können den MCP-Server mit Docker ausführen, um die Bereitstellung zu vereinfachen und eine konsistente Umgebung auf verschiedenen Plattformen zu gewährleisten.

Verwenden von Docker Compose (empfohlen)

Kopieren Sie die Beispielumgebungsdatei und konfigurieren Sie Ihre Anmeldeinformationen:

cp .env.example .env
# Edit .env file with your Luno API credentials

Starten Sie den Server:

docker compose up -d

Der Server ist im WebSocket-Modus unter ws://localhost:8765 verfügbar.

Protokolle anzeigen:

docker compose logs -f

Stoppen Sie den Server:

docker compose down

Docker direkt verwenden

Erstellen Sie das Image:

docker build -t mcp-luno .

Führen Sie den Container aus:

docker run -d \
  -p 8765:8765 \
  -e LUNO_API_KEY=your_api_key_here \
  -e LUNO_API_SECRET=your_api_secret_here \
  -e MCP_TRANSPORT=websocket \
  -e MCP_HOST=0.0.0.0 \
  -v ./certs:/app/certs \
  --name mcp-luno \
  mcp-luno

Verwendung mit KI-Assistenten

Nach dem Starten des Docker-Containers können Sie verschiedene KI-Assistenten verbinden, um den Luno MCP-Server zu verwenden:

Cursor

Fügen Sie Ihrer Cursorkonfiguration Folgendes hinzu:

{
  "mcp_servers": {
    "luno": {
      "type": "websocket",
      "url": "ws://localhost:8765"
    }
  }
}

Claude Desktop

In den Claude Desktop-Einstellungen haben Sie zwei Möglichkeiten, den MCP-Server zu konfigurieren:

Option 1: Docker verwenden (empfohlen)

{
  "mcpServers": {
    "luno": {
      "command": "docker",
      "args": ["compose", "up"],
      "cwd": "/path/to/mcp-luno",
      "transport": "websocket",
      "url": "ws://localhost:8765",
      "env": {
        "LUNO_API_KEY": "your_api_key_here",
        "LUNO_API_SECRET": "your_api_secret_here"
      }
    }
  }
}

Diese Konfiguration startet den Server in einem Docker-Container und stellt eine Verbindung über WebSocket her.

Option 2: Direkte Python-Ausführung verwenden

{
  "mcpServers": {
    "luno": {
      "command": "python",
      "args": ["-m", "src.main", "--transport", "stdio"],
      "cwd": "/path/to/mcp-luno",
      "transport": "stdio",
      "env": {
        "PYTHONPATH": "${workspaceFolder}",
        "LUNO_API_KEY": "your_api_key_here",
        "LUNO_API_SECRET": "your_api_secret_here"
      }
    }
  }
}

Diese Konfiguration führt den Python-Server direkt mithilfe des STDIO-Transports aus.

Hinweis: Ersetzen Sie /path/to/mcp-luno durch den tatsächlichen Pfad, in den Sie das Repository geklont haben.

Cline

Fügen Sie Ihrer Cline-Konfigurationsdatei Folgendes hinzu:

{
  "mcp": {
    "servers": {
      "luno": {
        "transport": "websocket",
        "url": "ws://localhost:8765"
      }
    }
  }
}

SSL-Unterstützung mit Docker

So verwenden Sie SSL mit dem Docker-Container:

Generieren Sie Zertifikate mit dem bereitgestellten Skript:

./generate_certificates.sh

Hängen Sie das Zertifikatsverzeichnis ein, wenn Sie den Container ausführen:

docker run -d \
  -p 8765:8765 \
  -e LUNO_API_KEY=your_api_key_here \
  -e LUNO_API_SECRET=your_api_secret_here \
  -e MCP_TRANSPORT=websocket \
  -e MCP_HOST=0.0.0.0 \
  -v ./certs:/app/certs \
  --name mcp-luno \
  mcp-luno

Manuelle Installation

Option A : Verwenden .env Datei

cp .env.example .env

Bearbeiten Sie dann die .env Datei, um Ihre Luno-API-Anmeldeinformationen hinzuzufügen:

LUNO_API_KEY=your_api_key_here
LUNO_API_SECRET=your_api_secret_here

Option B : Verwenden der VS Code MCP-Konfiguration

Bearbeiten Sie die Datei .vscode/mcp.json und fügen Sie Ihre Anmeldeinformationen zum Abschnitt env hinzu:

"env": {
  "PYTHONPATH": "${workspaceFolder}",
  "LUNO_API_KEY": "your_api_key_here",
  "LUNO_API_SECRET": "your_api_secret_here",
  "LOG_LEVEL": "INFO"
}

Hinweis : Ohne gültige API-Anmeldeinformationen sind nur öffentliche Endpunkte verfügbar. Empfehlung : Verwenden Sie aus Sicherheitsgründen beim Teilen von Code vorzugsweise Umgebungsvariablen.

Ausführen des Servers

Sie können den MCP-Server in zwei verschiedenen Transportmodi ausführen:

STDIO-Transport (Standard, einzelner Client)

Dies ist der Standardmodus, der eine einzelne Clientverbindung über die Standardeingabe/-ausgabe unterstützt:

python -m src.main --transport stdio

WebSockets-Transport (mehrere Clients)

Um mehrere Clientverbindungen gleichzeitig zu unterstützen, führen Sie den Server im WebSocket-Modus aus:

python -m src.main --transport websocket [--host HOST] [--port PORT]

Der WebSocket-Server wird standardmäßig unter ws://localhost:8765 gestartet.

Testen des WebSocket-Servers

Sie können den WebSocket-Server mit dem mitgelieferten Testclient testen:

python test_websocket_client.py

Dadurch lässt sich überprüfen, ob der Server WebSocket-Verbindungen korrekt verarbeitet und auf Anfragen reagiert.

Befehlszeilenoptionen

--transport {stdio,websocket} : Zu verwendender Transportmechanismus (Standard: stdio)
--host HOST : Host, an den bei Verwendung des WebSocket-Transports gebunden werden soll (Standard: localhost)
--port PORT : Port, an den bei Verwendung des WebSocket-Transports gebunden werden soll (Standard: 8765)

Umgebungsvariablen

Sie können den Transport auch mithilfe von Umgebungsvariablen konfigurieren:

MCP_TRANSPORT : Transportmechanismus („stdio“ oder „websocket“)
MCP_HOST : Host, an den für den WebSocket-Transport gebunden werden soll
MCP_PORT : Port für die Bindung zum WebSocket-Transport

Testen mit dem Standard-Client

Verwenden Sie zum Testen des STDIO-Transports den mitgelieferten Testclient:

python test_client.py

MCP-Protokollintegration

Dieser Server implementiert das Model Context Protocol, das die Interaktion von KI-Modellen über standardisierte JSON-RPC 2.0-Nachrichten ermöglicht. Der Server läuft standardmäßig über STDIO und ermöglicht so die einfache Integration mit VS Code-Erweiterungen und anderen MCP-kompatiblen Clients.

VS Code-Integration

Die Datei .vscode/mcp.json konfiguriert den Server für die Verwendung mit VS Code. Es stehen zwei Serverkonfigurationen zur Verfügung:

luno-mcp-server-stdio – Verwendet den STDIO-Transport (Standard-MCP-Verhalten)
luno-mcp-server-websocket - Verwendet den WebSocket-Transport für die Unterstützung mehrerer Clients

VS Code-Konfiguration

Um den WebSocket-Transport mit VS Code zu verwenden, enthält die Datei mcp.json eine Prozesstypkonfiguration:

"luno-mcp-server-websocket": {
  "type": "process",
  "command": "python",
  "args": ["-m", "src.main", "--transport", "websocket"],
  "env": {
    // environment variables
  }
}

Bei Verwendung des WebSocket-Transports startet VS Code den Server als Hintergrundprozess, anstatt über STDIO zu kommunizieren.

Konfigurieren des MCP-Servers in VS Code

Sie können den Server direkt aus der Datei .vscode/mcp.json konfigurieren:

{
  "servers": {
    "luno-mcp-server": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "src.main"],
      "env": {
        "PYTHONPATH": "${workspaceFolder}",
        "LUNO_API_KEY": "your_api_key_here",
        "LUNO_API_SECRET": "your_api_secret_here",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Diese Konfiguration wird von VS Code-Erweiterungen verwendet, die das MCP-Protokoll unterstützen, wodurch die Integration mit KI-Modellen und anderen Tools vereinfacht wird.

Verfügbare Methoden

Verfahren	Beschreibung	Authentifizierung erforderlich
`describe_capabilities`	Gibt Informationen zu Serverfunktionen zurück	NEIN
`get_crypto_price`	Aktuellen Preis für ein bestimmtes Handelspaar abrufen	NEIN
`get_market_overview`	Verschaffen Sie sich einen Überblick über alle verfügbaren Märkte	NEIN
`get_account_balance`	Holen Sie sich den Kontostand aller Konten	Ja
`place_order`	Eine neue Bestellung aufgeben	Ja
`cancel_order`	Eine bestehende Bestellung stornieren	Ja
`get_order_status`	Den Status einer Bestellung abrufen	Ja
`get_transaction_history`	Abrufen des Transaktionsverlaufs für ein Konto	Ja
`get_fees`	Erhalten Sie Gebühreninformationen für ein Handelspaar	Ja

Beispielanfragen

Holen Sie sich Serverfunktionen:

{
  "jsonrpc": "2.0",
  "method": "describe_capabilities",
  "params": {},
  "id": 1
}

Bitcoin-ZAR-Preis abrufen:

{
  "jsonrpc": "2.0",
  "method": "get_crypto_price",
  "params": {"pair": "XBTZAR"},
  "id": 2
}

Entwicklung

Projektstruktur

├── .env                 # Environment variables (API credentials)
├── .gitignore           # Git ignore configuration
├── .vscode/             # VS Code specific settings
│   └── mcp.json         # MCP configuration for VS Code
├── src/                 # Source code
│   ├── main.py          # Entry point
│   └── luno_mcp_server/ # MCP server implementation
│       ├── luno_client.py # Luno API client
│       └── server.py    # MCP server core
├── tests/               # Test suite
├── test_client.py       # Simple test client for the MCP server
├── requirements.txt     # Project dependencies
└── setup.py             # Package setup

Ausführen von Tests

python -m pytest tests/

Neue Funktionen hinzufügen

So fügen Sie neue Luno-API-Funktionen hinzu:

Erweitern Sie die LunoClient -Klasse in src/luno_mcp_server/luno_client.py mit neuen API-Methoden
Fügen Sie entsprechende Methoden in der LunoMCPServer -Klasse in src/luno_mcp_server/server.py
Aktualisieren Sie die MCP_METHODS -Liste in server.py und registrieren Sie Ihre Methoden in der Funktion _register_methods
Fügen Sie Tests im Verzeichnis tests/ “ hinzu

Architektur

Der MCP-Server verwendet eine einfache Architektur:

JSON-RPC 2.0 für die Kommunikation
Standard-Eingabe/Ausgabe (STDIO) für den Transport
Luno-API-Client für Kryptowährungsoperationen

Fehlerbehebung

Häufige Probleme

API-Authentifizierungsfehler : Stellen Sie sicher, dass Ihre Luno-API-Schlüssel entweder in der .env Datei oder in .vscode/mcp.json korrekt eingestellt sind.
Importfehler : Stellen Sie sicher, dass Sie die virtuelle Umgebung aktiviert haben
Ratenbegrenzung : Die Luno-API verfügt über Ratenbegrenzungen – implementieren Sie eine Wiederholungslogik für den Produktionseinsatz

Konfigurationspriorität

Beim Starten des Servers werden die Konfigurationseinstellungen in dieser Prioritätsreihenfolge geladen:

Umgebungsvariablen, die über die MCP-Konfiguration übergeben werden (höchste Priorität)
Werte in der .env Datei
Standardwerte im Code (niedrigste Priorität)

Dies bedeutet, dass Sie in der MCP-Konfiguration Werte festlegen können, um alle vorhandenen Werte in Ihrer .env Datei zu überschreiben.

Multi-Client-Unterstützung

Dieser MCP-Server unterstützt mehrere Clientverbindungen gleichzeitig über WebSockets. Ausführliche Informationen finden Sie unter MULTI_CLIENT_SUPPORT.md .

Transportmöglichkeiten

Der Server unterstützt zwei Transportmechanismen:

STDIO (Standard): Standard-Eingabe/Ausgabe – einzelner Client, verwendet von VS Code MCP
WebSockets : Netzwerktransport – mehrere Clients mit Sicherheitsfunktionen

Ausführen mit WebSockets-Transport

Grundlegende Verwendung:

python -m src.main --transport websocket --host localhost --port 8765

Mit Sicherheitsoptionen:

python -m src.main --transport websocket --host localhost --port 8765 \
  --max-connections 50 --max-message-size 1048576 --rate-limit 100

Mit SSL/TLS-Verschlüsselung:

# First generate certificates
./generate_certificates.sh

# Then run with SSL support
python -m src.main --transport websocket --ssl-cert ./certs/server.crt --ssl-key ./certs/server.key

WebSocket-Client-Tools

Das Repository enthält zwei Client-Tools:

test_websocket_client.py : Einfacher Testclient
python test_websocket_client.py
enhanced_websocket_client.py : Erweiterter Client mit Multi-Client-Simulation
# Single client mode python enhanced_websocket_client.py --mode single # Multi-client simulation (3 clients) python enhanced_websocket_client.py --mode multi --clients 3

Lizenz

MIT-Lizenz

Jedem, der eine Kopie dieser Software und der zugehörigen Dokumentationsdateien erhält, wird hiermit unentgeltlich die Erlaubnis erteilt.

Integrations