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.

Related MCP server: @1claw/mcp

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 venv aislado y coloca op-mcp en el PATH. Para actualizar después de cambios en el código:

uv tool install --force .

--force sobrescribe el punto de entrada existente y reconstruye desde el código fuente. (--reinstall vuelve a descargar las dependencias de PyPI; no es necesario para una instalación de ruta local.)

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:

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 deben solicitar confirmación.

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

Desarrollo

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

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 por defecto.

Herramientas

10 herramientas en total: 3 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 tarea 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.