MCP-Server: Firmendaten für Claude, mit Rollen und Audit-Protokoll

Anleitung (README)

# Firmensoftware mit Claude verbinden (MCP-Server)

Dieser Server macht Ihre Firmendaten (hier: Kunden, Auftraege, Rechnungen) fuer Claude nutzbar - ueber das
offene **Model Context Protocol (MCP)**. Claude kann damit Kunden suchen, offene Rechnungen auflisten, den Stand
eines Auftrags nennen und - nur mit Buchhaltungsrecht - eine Rechnung als bezahlt buchen.

## Werkzeuge

| Werkzeug | Art | Rolle |
|---|---|---|
| `kunde_suchen(suchbegriff, limit=20)` | lesend | lesen, buchhaltung |
| `offene_rechnungen(kunde_id=None)` | lesend | lesen, buchhaltung |
| `auftrag_status(auftrag_nr)` | lesend | lesen, buchhaltung |
| `rechnung_als_bezahlt_markieren(rechnung_nr, bezahlt_am)` | schreibend | nur buchhaltung |

## Sicherheit

* **Rollen per Token.** Jeder Arbeitsplatz bekommt ein eigenes Token. In `rollen.json` steht nur dessen
  SHA-256-Wert und die Rolle - nie das Token selbst. Unbekanntes Token: jeder Aufruf wird abgewiesen.
* **Eingabepruefung.** Nummern muessen dem Format (R-12345, A-12345) entsprechen, Datumsangaben muessen gueltig
  und nicht in der Zukunft sein, Suchbegriffe 1-80 Zeichen.
* **Keine SQL-Injection.** Alle Abfragen sind parametrisiert; `%` und `_` im Suchbegriff werden woertlich gesucht.
  Lesende Werkzeuge oeffnen die Datenbank schreibgeschuetzt.
* **Audit-Log.** Jeder Aufruf - erlaubt, abgewiesen oder fehlerhaft - steht genau einmal in `audit.jsonl`
  (Zeit, Rolle, Token-Fingerabdruck, Werkzeug, Argumente, Ergebnis).

## Einrichtung

1. Python 3.11 oder neuer installieren, dann: `pip install "mcp>=2.3"`
2. Token erzeugen und eintragen:

   ```
   python -c "import secrets,hashlib; t=secrets.token_urlsafe(24); print('Token:', t); print('SHA-256:', hashlib.sha256(t.encode()).hexdigest())"
   ```

   `rollen.json`:

   ```json
   { "<SHA-256 von Token 1>": "lesen", "<SHA-256 von Token 2>": "buchhaltung" }
   ```

3. In **Claude Desktop**: Einstellungen > Entwickler > Konfiguration bearbeiten. Das oeffnet
   `claude_desktop_config.json` (Windows: `%APPDATA%\Claude\claude_desktop_config.json`, macOS:
   `~/Library/Application Support/Claude/claude_desktop_config.json`). Dort eintragen
   (Vorlage: `claude_desktop_config.beispiel.json`):

   ```json
   {
     "mcpServers": {
       "firmen-software": {
         "command": "C:/Python312/python.exe",
         "args": ["C:/Firma/mcp/firmen_mcp_server.py"],
         "env": {
           "FIRMA_DB": "C:/Firma/daten/firma.db",
           "FIRMA_ROLLEN": "C:/Firma/mcp/rollen.json",
           "FIRMA_AUDIT": "C:/Firma/mcp/audit.jsonl",
           "FIRMA_MCP_TOKEN": "<persoenliches Token>"
         }
       }
     }
   }
   ```

4. Claude Desktop neu starten. Unter dem Werkzeug-Symbol erscheint "firmen-software" mit vier Werkzeugen.
   Fuer **Claude Code**: `claude mcp add firmen-software -e FIRMA_DB=... -e FIRMA_ROLLEN=... -e FIRMA_AUDIT=... -e FIRMA_MCP_TOKEN=... -- python C:/Firma/mcp/firmen_mcp_server.py`

## Tests

`probe_mcp_anbindung.py` startet den Server als echten Unterprozess und prueft ueber den MCP-Client:
Werkzeugliste und Schemas, jede Antwort gegen die Datenbank, abgewiesene Schreibversuche ohne Recht,
Injection-Versuche ohne Wirkung und das Audit-Log (jeder Aufruf genau einmal). Zur Kontrolle laeuft dieselbe
Pruefung gegen absichtlich verschlechterte Server (ohne Rechtepruefung, ohne Audit, ohne Maskierung) - die
muessen durchfallen.

## Grenzen

* Dieses Muster (lokaler Unterprozess ueber stdio, Token in der Umgebung) ist fuer den eigenen Rechner gedacht.
  Ein zentral betriebener Server ueber HTTP braucht eine Anmeldung per OAuth 2.1.
* Fuer Ihre echte Software (ERP, Shop, CRM) werden die Werkzeuge auf deren API oder Datenbank angepasst; dafuer
  ist ein Zugang mit passenden Rechten noetig.
* Rechte gelten je Werkzeug, nicht je Datensatz. Das Audit-Log ist eine lokale Datei ohne Manipulationsschutz.

So etwas für deinen Betrieb?

Beschreib kurz, was du brauchst. Du bekommst einen Festpreis, bevor ich anfange; ohne dein Ja passiert nichts.

Zur Werkstatt