op-mcp

MCP 服务器，封装了 1Password CLI (op)，为 MCP 客户端（Cowork、Claude Code、Claude Desktop）提供密钥访问和条目管理功能。

架构

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

Python 服务器设计得非常轻量。每个工具处理程序都会调用 op CLI，并解析 JSON 或返回原始输出。CLI 负责处理生物识别认证、会话缓存和所有密码库访问。Python 端负责处理 MCP 协议和 argv 构建。

这种设计在构建上是无状态的：每次工具调用都会启动一个新的 CLI 进程。op 会在 1Password 桌面应用内缓存其自己的会话——我们不管理会话、令牌或凭据。完整原理请参阅 docs/design-notes.md。

先决条件

• Python 3.11 或更高版本

• 已安装 op CLI 并将其添加到 PATH。通过 Homebrew 安装： brew install --cask 1password-cli（已在 v2.33.1 版本测试）。

• 已安装 1Password 桌面应用并启用了 CLI 集成： 1Password → 设置 → 开发者 → ✓ “集成 1Password CLI”。

• 已为 CLI 授权启用 Touch ID（在同一设置面板中）。

安装

uv tool install .

这将创建一个隔离的 venv 并将 op-mcp 添加到 PATH。代码更改后如需升级：

uv tool install --force --reinstall .

这两个标志都是必需的——--force 会覆盖现有的可执行文件，--reinstall 会绕过构建缓存。

运行

服务器通过 stdio 进行通信，因此它通常由 MCP 客户端启动，而不是手动调用。进行本地冒烟测试：

op-mcp

服务器将日志记录到 stderr，并在 stdin 上等待 MCP 协议消息。按 Ctrl-C 退出。

配置 MCP 客户端

Claude Desktop： 设置 → 连接器 → 添加 → 输入 op-mcp 作为命令。或者直接编辑 claude_desktop_config.json：

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

Claude Code： 添加到 .mcp.json（项目级）或 ~/.claude/mcp.json（全局级），格式相同。

Cowork： 通过 Cowork 的 MCP 服务器配置添加。

推荐权限

读取操作可以安全允许；写入操作应要求确认。

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

开发

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

测试使用伪造的 op 二进制文件（临时 shell 脚本），因此不需要真实的 CLI 或 1Password 访问权限。实时测试（标记为 @pytest.mark.live）针对真实的 CLI 运行，会触发 Touch ID，默认情况下会被跳过。

工具

共 9 个工具：2 个基础设施工具，4 个读取工具，3 个写入工具。

基础设施

读取工具

写入工具

暂未实现（目前）

• op signin / op signout — 会话管理是 op 的工作。

• op document / op vault — 等出现用例时再添加。

• op inject / op run — 模板注入和环境变量加载工作流是命令行便利功能，没有简洁的 MCP 等效项。

• 服务账户令牌 — 此服务器假设使用生物识别桌面认证。