Frappe Bench & Site Manager — MCP Server

Verwalten Sie Ihre lokalen Frappe-Benches und -Sites direkt von Claude.ai (Web + Mobil) aus. Verwendet FastMCP über HTTP mit einem statischen Ngrok-Tunnel.

📱 Claude.ai  →  🌐 Ngrok (permanent URL)  →  🖥️ MCP Server (localhost:8000)  →  🔧 Frappe Benches

Verfügbare Tools

Tool	Kategorie	Funktion
`bench_restart`	Bench-Operationen	Startet Supervisor/Bench-Dienste neu
`list_sites`	Site-Verwaltung	Listet Benches, Sites, Apps und Status auf
`frappe_api`	DocType-Daten	Authentifizierte REST-API-Aufrufe
`bench_execute`	Konsole	Führt Python im Frappe-Kontext aus
`get_logs`	Protokolle	Ruft Site-/Bench-Protokolldateien ab und filtert diese
`get_config_overview`	Konfiguration	Zeigt konfigurierte Benches an (keine Geheimnisse werden offengelegt)

Voraussetzungen

Python 3.10+
Eine oder mehrere Frappe-Benches, die bereits lokal eingerichtet sind und funktionieren
ngrok-Konto (der kostenlose Tarif reicht aus)

Schritt 1: Abhängigkeiten installieren

git clone <this-repo>
cd frappe-mcp
pip install -r requirements.txt

Schritt 2: Konfiguration

cp config.example.json config.json

Bearbeiten Sie die config.json:

{
  "benches": [
    {
      "id": "bench1",
      "label": "Main Dev Bench",
      "path": "/home/youruser/frappe-bench",
      "bench_cmd": "/home/youruser/frappe-bench/env/bin/bench"
    }
  ],
  "site_credentials": {
    "mysite.localhost": {
      "api_key": "YOUR_API_KEY",
      "api_secret": "YOUR_API_SECRET",
      "port": 8000
    }
  }
}

Wichtig: config.json wird von git ignoriert – committen Sie diese niemals.

Schritt 3: Frappe-API-Anmeldedaten abrufen

Für jede Site, auf die Sie über frappe_api oder bench_execute zugreifen möchten:

Öffnen Sie die Frappe-Site in Ihrem Browser
Gehen Sie zu Einstellungen → API-Zugriff
Klicken Sie auf Schlüssel generieren (für Ihren Administrator-Benutzer)
Kopieren Sie api_key und api_secret in die config.json → site_credentials

Schritt 4: Starten des MCP-Servers

python main.py

Sie sollten Folgendes sehen:

🚀  Frappe MCP Server starting...
    Benches configured : 1
    Sites with creds   : 1
    Listening on       : http://0.0.0.0:8000
    MCP endpoint       : http://0.0.0.0:8000/mcp
    Audit log          : mcp_audit.log

Schritt 5: Ngrok einrichten (einmalig)

Ngrok installieren

macOS (Homebrew):

brew install ngrok/ngrok/ngrok

Linux:

curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | sudo tee /etc/apt/sources.list.d/ngrok.list
sudo apt update && sudo apt install ngrok

Oder direkt herunterladen: https://ngrok.com/download

Authentifizierungs-Token hinzufügen

ngrok config add-authtoken YOUR_AUTHTOKEN

Holen Sie sich Ihr Token von: https://dashboard.ngrok.com/get-started/your-authtoken

Tunnel mit Ihrer kostenlosen statischen Domain starten

ngrok http 8000 --domain=yourname.ngrok-free.app

Holen Sie sich eine kostenlose statische Domain: ngrok Dashboard → Cloud Edge → Domains → New Domain

Ihre permanente MCP-URL lautet dann:

https://yourname.ngrok-free.app/mcp

Schritt 6: Verbindung zu Claude.ai herstellen

Öffnen Sie claude.ai → Einstellungen → Integrationen
Klicken Sie auf Integration hinzufügen
Geben Sie die URL ein: https://yourname.ngrok-free.app/mcp
Klicken Sie auf Hinzufügen – das war's

Funktioniert von Ihrem Telefon und Laptop aus überall, solange Ihr Laptop läuft.

Schritt 7: Automatischer Start beim Booten (optional)

Linux (systemd)

Erstellen Sie /etc/systemd/system/frappe-mcp.service:

[Unit]
Description=Frappe MCP Server
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/home/youruser/frappe-mcp
ExecStart=/usr/bin/python3 /home/youruser/frappe-mcp/main.py
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable frappe-mcp
sudo systemctl start frappe-mcp

macOS (launchd)

Erstellen Sie ~/Library/LaunchAgents/com.frappe.mcp.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.frappe.mcp</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/python3</string>
        <string>/Users/youruser/frappe-mcp/main.py</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/Users/youruser/frappe-mcp</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/youruser/frappe-mcp/mcp_stdout.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/youruser/frappe-mcp/mcp_stderr.log</string>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/com.frappe.mcp.plist

Tests ausführen

python test_tools.py

Es wird keine echte Frappe-Bench benötigt – alle Tools werden mit einer Mock-Konfiguration getestet.

Sicherheitshinweise

config.json wird niemals committet (gitignored)
API-Schlüssel werden niemals in Tool-Antworten offengelegt (get_config_overview zeigt nur "configured"/"missing" an)
Alle Subprozess-Aufrufe verwenden shell=False – keine Shell-Injection möglich
bench_execute verfügt über einen zweistufigen Sicherheitsscanner: harte Blockaden und weiche Warnungen
Blockierte Muster (konfigurierbar): DROP, TRUNCATE, os.system, exec(, eval( usw.
Ratenbegrenzung: 30 Anfragen/Minute pro IP (konfigurierbar)
Alle Tool-Aufrufe werden an mcp_audit.log angehängt

Beispiel-Prompts für Claude

List all my Frappe sites and their status.

How many NGO records are on site1.localhost in bench1?

Show me the last 50 error log lines for site1.localhost — filter for "PermissionError".

Restart the web worker on bench1.

What's in the mGrant Settings module field for site1.localhost?

Show me all active Grants on site1.localhost with fields name, grant_name, grant_status.

Dateistruktur

frappe-mcp/
├── main.py               # FastMCP server + tool registration
├── config.py             # Config loader + validator + singleton
├── security.py           # Input sanitizer, command blocker, rate limiter
├── logger.py             # Audit logger → mcp_audit.log
├── tools/
│   ├── bench_ops.py      # bench_restart (+ Phase 2 stubs)
│   ├── site_manager.py   # list_sites (+ Phase 2 stub)
│   ├── frappe_api.py     # frappe_api (+ Phase 2 stub)
│   ├── executor.py       # bench_execute
│   └── log_reader.py     # get_logs
├── config.json           # Your config (gitignored)
├── config.example.json   # Template (committed)
├── requirements.txt
├── .gitignore
├── test_tools.py         # Test suite (mock config, no bench needed)
└── README.md

Fehlerbehebung

config.json not found → Führen Sie cp config.example.json config.json aus und tragen Sie Ihre Bench-Pfade ein.

Bench path '/home/...' does not exist → Der path in config.json → benches muss ein existierendes Verzeichnis sein.

bench command not found → Verwenden Sie den vollständigen Pfad zum Bench-Binary, z. B. /home/user/frappe-bench/env/bin/bench.

No credentials configured for site → Fügen Sie api_key/api_secret für diese Site in config.json → site_credentials hinzu.

Authentication failed (401) → Generieren Sie die API-Schlüssel in der Frappe-Site neu: Einstellungen → API-Zugriff.

Ngrok zeigt ERR_NGROK_3200 → Ihre statische Domain ist möglicherweise nicht aktiviert. Überprüfen Sie das ngrok Dashboard → Domains.

Frappe MCP Server