op-mcp

MCP server that wraps the 1Password CLI (op), exposing secret access and item management to MCP clients (Cowork, Claude Code, Claude Desktop).

Architecture

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

The Python server is deliberately thin. Every tool handler shells out to the op CLI and either parses JSON or returns the raw output. The CLI handles biometric auth, session caching, and all vault access. The Python side handles MCP protocol and argv construction.

This design is stateless by construction: each tool call spawns a fresh CLI process. op caches its own session inside the 1Password desktop app — we don't manage sessions, tokens, or credentials. See docs/design-notes.md for the full rationale.

Prerequisites

• Python 3.11 or newer
• The op CLI installed and on PATH. Install via Homebrew: brew install --cask 1password-cli (tested with v2.33.1).
• The 1Password desktop app installed and CLI integration enabled: 1Password → Settings → Developer → ✓ "Integrate with 1Password CLI".
• Touch ID enabled for CLI authorization (same settings pane).

Install

uv tool install .

This creates an isolated venv and puts op-mcp on PATH. To upgrade after code changes:

uv tool install --force .

--force overwrites the existing entry point and rebuilds from source. (--reinstall re-downloads PyPI dependencies — not needed for a local path install.)

Run

The server communicates over stdio, so it's normally launched by an MCP client rather than invoked by hand. For local smoke testing:

op-mcp

The server logs to stderr and waits for MCP protocol messages on stdin. Press Ctrl-C to exit.

Configure an MCP client

Claude Desktop: Settings → Connectors → Add → enter op-mcp as the command. Or edit claude_desktop_config.json directly:

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

Claude Code: Add to .mcp.json (project) or ~/.claude/mcp.json (global) with the same shape.

Cowork: Add via Cowork's MCP server configuration.

Recommended permissions

Reads are safe to allow; writes should ask for confirmation.

{
  "permissions": {
    "allow": [
      "mcp__op__op_ping",
      "mcp__op__op_version",
      "mcp__op__op_whoami",
      "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"
    ]
  }
}

Development

uv sync --extra dev
make test                                  # uv run pytest (fake `op` binary)
RUN_LIVE_OP_TESTS=1 uv run pytest -m live  # live tests against real op CLI
make lint                                  # ruff + pyright
make install-mcp                           # reinstall after code changes

Tests use a fake op binary (temporary shell scripts), so they don't require the real CLI or 1Password access. Live tests (marked @pytest.mark.live) run against the real CLI, trigger Touch ID, and are skipped by default.

Tools

10 tools total: 3 infrastructure, 4 read, 3 write.

Infrastructure

Read tools

Write tools

Out of scope (for now)

• op signin / op signout — session management is op's job.
• op document / op vault — add when use cases emerge.
• op inject / op run — template injection and env-loading workflows are command-line conveniences without a clean MCP equivalent.
• Service account tokens — this server assumes biometric desktop auth.