op-mcp

Servidor MCP que envuelve la CLI de 1Password (op), exponiendo el acceso a secretos y la gestión de elementos a clientes MCP (Cowork, Claude Code, Claude Desktop).

Arquitectura

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

El servidor de Python es deliberadamente ligero. Cada manejador de herramientas ejecuta comandos en la CLI de op y analiza el JSON o devuelve la salida sin procesar. La CLI gestiona la autenticación biométrica, el almacenamiento en caché de sesiones y todo el acceso a la caja fuerte. El lado de Python gestiona el protocolo MCP y la construcción de argumentos.

Este diseño es sin estado por construcción: cada llamada a una herramienta genera un nuevo proceso de CLI. op almacena su propia sesión dentro de la aplicación de escritorio de 1Password; nosotros no gestionamos sesiones, tokens ni credenciales. Consulta docs/design-notes.md para conocer la justificación completa.

Requisitos previos

• Python 3.11 o superior

• La CLI op instalada y en el PATH. Instalar mediante Homebrew: brew install --cask 1password-cli (probado con v2.33.1).

• La aplicación de escritorio de 1Password instalada y con la integración CLI habilitada: 1Password → Ajustes → Desarrollador → ✓ "Integrar con la CLI de 1Password".

• Touch ID habilitado para la autorización de la CLI (mismo panel de ajustes).

Instalación

uv tool install .

Esto crea un entorno virtual (venv) aislado y coloca op-mcp en el PATH. Para actualizar después de cambios en el código:

uv tool install --force --reinstall .

Ambas banderas son necesarias: --force sobrescribe el ejecutable existente, --reinstall evita la caché de compilación.

Ejecución

El servidor se comunica a través de stdio, por lo que normalmente lo inicia un cliente MCP en lugar de invocarse manualmente. Para pruebas locales rápidas:

op-mcp

El servidor registra en stderr y espera mensajes del protocolo MCP en stdin. Presiona Ctrl-C para salir.

Configurar un cliente MCP

Claude Desktop: Ajustes → Conectores → Añadir → introduce op-mcp como comando. O edita claude_desktop_config.json directamente:

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

Claude Code: Añadir a .mcp.json (proyecto) o ~/.claude/mcp.json (global) con la misma estructura.

Cowork: Añadir a través de la configuración del servidor MCP de Cowork.

Permisos recomendados

Las lecturas son seguras de permitir; las escrituras deberían solicitar confirmación.

{
  "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"
    ]
  }
}

Desarrollo

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

Las pruebas utilizan un binario op falso (scripts de shell temporales), por lo que no requieren la CLI real ni acceso a 1Password. Las pruebas en vivo (marcadas con @pytest.mark.live) se ejecutan contra la CLI real, activan Touch ID y se omiten de forma predeterminada.

Herramientas

9 herramientas en total: 2 de infraestructura, 4 de lectura, 3 de escritura.

Infraestructura

Herramientas de lectura

Herramientas de escritura

Fuera del alcance (por ahora)

• op signin / op signout: la gestión de sesiones es trabajo de op.

• op document / op vault: añadir cuando surjan casos de uso.

• op inject / op run: la inyección de plantillas y los flujos de trabajo de carga de entorno son comodidades de la línea de comandos sin un equivalente limpio en MCP.

• Tokens de cuenta de servicio: este servidor asume autenticación biométrica de escritorio.