op-mcp

MCP-Server, der die 1Password CLI (op) umschließt und den Zugriff auf Geheimnisse sowie die Elementverwaltung für MCP-Clients (Cowork, Claude Code, Claude Desktop) bereitstellt.

Architektur

MCP client (Cowork, Claude Code, Claude Desktop)
  ↓ stdio (MCP protocol)
op-mcp (this Python server)
  ↓ subprocess per tool call
op CLI (1Password CLI)
  ↓ biometric prompt (Touch ID) + 1Password desktop app
1Password vaults

Der Python-Server ist bewusst schlank gehalten. Jeder Tool-Handler ruft die op-CLI auf und parst entweder JSON oder gibt die Rohausgabe zurück. Die CLI übernimmt die biometrische Authentifizierung, das Sitzungs-Caching und den gesamten Tresorzugriff. Die Python-Seite kümmert sich um das MCP-Protokoll und die Erstellung der Argumente.

Dieses Design ist konstruktionsbedingt zustandslos: Jeder Tool-Aufruf startet einen neuen CLI-Prozess. op speichert seine eigene Sitzung innerhalb der 1Password-Desktop-App – wir verwalten keine Sitzungen, Token oder Anmeldedaten. Siehe docs/design-notes.md für die vollständige Begründung.

Voraussetzungen

• Python 3.11 oder neuer

• Die op-CLI muss installiert und im PATH vorhanden sein. Installation via Homebrew: brew install --cask 1password-cli (getestet mit v2.33.1).

• Die 1Password-Desktop-App muss installiert sein und die CLI-Integration aktiviert sein: 1Password → Einstellungen → Entwickler → ✓ "In 1Password CLI integrieren".

• Touch ID für die CLI-Autorisierung aktiviert (im selben Einstellungsbereich).

Installation

uv tool install .

Dies erstellt ein isoliertes venv und fügt op-mcp zum PATH hinzu. Zum Aktualisieren nach Code-Änderungen:

uv tool install --force --reinstall .

Beide Flags sind erforderlich – --force überschreibt die vorhandene ausführbare Datei, --reinstall umgeht den Build-Cache.

Ausführung

Der Server kommuniziert über stdio, daher wird er normalerweise von einem MCP-Client gestartet und nicht manuell aufgerufen. Für lokale Tests:

op-mcp

Der Server protokolliert nach stderr und wartet auf MCP-Protokollnachrichten auf stdin. Drücken Sie Strg-C zum Beenden.

Konfiguration eines MCP-Clients

Claude Desktop: Einstellungen → Connectors → Hinzufügen → op-mcp als Befehl eingeben. Oder bearbeiten Sie claude_desktop_config.json direkt:

{
  "mcpServers": {
    "op": {
      "command": "op-mcp"
    }
  }
}

Claude Code: Fügen Sie es zu .mcp.json (Projekt) oder ~/.claude/mcp.json (global) mit der gleichen Struktur hinzu.

Cowork: Über die MCP-Server-Konfiguration von Cowork hinzufügen.

Empfohlene Berechtigungen

Lesezugriffe können sicher gewährt werden; Schreibzugriffe sollten eine Bestätigung erfordern.

{
  "permissions": {
    "allow": [
      "mcp__op__op_ping",
      "mcp__op__op_version",
      "mcp__op__op_list_vaults",
      "mcp__op__op_get_item",
      "mcp__op__op_read_secret",
      "mcp__op__op_list_items"
    ],
    "ask": [
      "mcp__op__op_create_item",
      "mcp__op__op_edit_item",
      "mcp__op__op_delete_item"
    ]
  }
}

Entwicklung

uv sync --extra dev
uv run pytest                              # unit tests (fake `op` binary)
RUN_LIVE_OP_TESTS=1 uv run pytest -m live  # live tests against real op CLI
uv run ruff check
uv run pyright

Tests verwenden eine gefälschte op-Binärdatei (temporäre Shell-Skripte), sodass sie weder die echte CLI noch 1Password-Zugriff benötigen. Live-Tests (gekennzeichnet mit @pytest.mark.live) laufen gegen die echte CLI, lösen Touch ID aus und werden standardmäßig übersprungen.

Tools

Insgesamt 9 Tools: 2 Infrastruktur, 4 Lesen, 3 Schreiben.

Infrastruktur

Lese-Tools

Schreib-Tools

Nicht im Umfang enthalten (vorerst)

• op signin / op signout — Sitzungsverwaltung ist Aufgabe von op.

• op document / op vault — Hinzufügen, wenn Anwendungsfälle entstehen.

• op inject / op run — Vorlagen-Injektion und Umgebungs-Lade-Workflows sind Befehlszeilen-Annehmlichkeiten ohne sauberes MCP-Äquivalent.

• Service-Account-Token — dieser Server setzt biometrische Desktop-Authentifizierung voraus.