1password

1Password MCP 服务

为你的 AI 助手提供通往 1Password 的安全入口，而不是把一堆密码放进聊天记录。

@takescake/1password-mcp 是一个社区开发的 Model Context Protocol (MCP) 服务。它让 Claude、Cursor、VS Code Copilot、OpenAI Codex、Gemini 和其他 MCP 客户端通过 1Password Service Account 管理保险库和凭据。

基于 MCP TypeScript SDK v2 构建，并支持 2026-07-28 协议协商（以及旧版客户端）。机密信息保留在 1Password 中；Agent 优先使用 op:// 引用和 op_run，避免明文进入模型对话记录。

这不是 1Password 的官方产品。 由社区构建，采用 Apache 2.0 许可证。

---

适用对象

你是……	你将获得……
非技术人员	一次性设置：创建服务账户，将令牌粘贴到 AI 应用的 MCP 设置中，然后用日常语言提出请求（“列出我的 automation 保险库”“轮换 staging 数据库密码”）。
Agent / 大模型	15 个类型化工具、4 个工作流提示词、3 个可浏览资源，以及明确的规则：优先使用 op_run + op://，而不是透露机密信息。
开发者 / SRE	完整的项目 CRUD、安全备注、密码生成、保险库允许列表、macOS 上的 Keychain 令牌加载，以及适用于 CI 的环境配置。

---

团队选择此服务的原因

• 安全优先的默认设置 — password_read 返回元数据，而 item_get 会隐藏包含机密信息的字段（密码、SSH 密钥、OTP 种子、卡号），除非你通过 reveal: true 选择显示。
• op_run（相当于 MCP 版的 op run） — 将 op://vault/item/field 注入本地命令的环境；返回的 stdout/stderr 会尽力对已解析的机密信息进行脱敏（包括常见编码）。
• 完整的保险库工具集 — 列出、搜索、获取、编辑、创建登录信息和备注、轮换密码、归档或删除。
• 引导式提示词 — 密码生成、凭据轮换、保险库审计和机密引用辅助工具。
• 可浏览资源 — 通过 onepassword://… URI 提供保险库和项目目录（资源负载中不含机密信息）。
• 现代 MCP — stdio 传输、Zod 4 架构、MCP 2026-07-28 协商，并兼容旧版客户端。

---

你将获得什么

工具（15 个）

按 Agent 和用户的实际使用方式分组。

发现

工具	功能
vault_list	列出服务账户可访问的保险库（id、名称、描述、类型）；如果设置了允许列表，则仅列出其中的保险库。
item_lookup	按标题子字符串搜索保险库；可选 limit（最大值为 200）。
item_list	列出保险库中的所有项目（id、标题、类别、标签、updatedAt）——绝不包含机密信息。

读取（默认安全）

工具	功能说明
item_get	完整条目信息：标题、类别、标签、备注和字段。除非设置 reveal: true，否则密码及其他隐藏字段、SSH 私钥、OTP 种子、银行卡号等敏感值均会隐藏；仅显示已知的非敏感字段类型。**备注将原样返回。**接受 op://… 或 vaultId + itemId。
password_read	通过 op://… 或 ID 读取单个字段（默认为 password）。**除非设置 reveal: true，否则仅返回元数据。**建议使用 op_run 来使用密钥。
op_check_ref	验证 op://vault/item/field，并且仅返回非敏感元数据（库、条目、字段）。绝不返回字段值。

创建与更新

工具	功能说明
password_create	创建 Login 或 Password 条目（用户名、URL、标签、备注）。returnSecret 默认为 false。
note_create	创建 Secure Note，并可选添加标签和自定义字段。
password_update	轮换密码／隐藏字段（如果字段不存在则创建）。
item_edit	更新标题、备注（空字符串会清除备注）、标签、URL；新增或更新字段，或移除字段。未引用的字段保持不变。
password_generate	以密码学安全方式生成随机密码（长度为 8–128；可启用或禁用符号、数字和大写字母）。
password_generate_memorable	从约 500 个词的列表中生成易记的密码短语（词数、分隔符、数字／符号后缀）。

使用密钥而不泄露

工具	功能说明
op_run	使用环境变量运行本地命令（command 或 argv）。与 op://… 匹配的值只会在子进程中解析；解析出的密钥会从返回的输出中脱敏（尽力而为，详见“安全与隐私”）。每个输出流最多保留 5 MiB；超时会终止整个进程树。可选参数：cwd、shell、timeout_ms、stdin。

软删除与销毁

工具	功能说明
item_archive	将条目移至存档（在普通视图中隐藏）。
item_delete	永久删除条目——无法撤销。

提示词（4）

提示词	适用场景
generate-secure-password	生成随机或易记的密码，并可选择存储，而不会将密码直接输出到聊天中。
credential-rotation	查找 → 验证访问权限 → 生成 → 更新 → 确认 op:// 引用。
vault-audit	按类别盘点一个库；标记重复项／异常项——绝不泄露密钥。
secret-reference-helper	根据名称生成可直接粘贴的 op://vault/item/field。

资源（3）

URI	内容
onepassword://config	非敏感的服务配置（名称、版本、日志级别、令牌来源、Node 版本）。
onepassword://vaults	可访问库的 JSON 列表（如果设置了允许列表，则仅包含允许列表中的库）。
onepassword://vaults/{vaultId}/items	URI 模板（由 resources/templates/list 列出）：单个库的 JSON 条目元数据（不含敏感值）。

**从 4.x 升级：**资源 URI 曾以 1password:// 开头，而 MCP 客户端无法读取这些 URI（URI 方案不能以数字开头）。请将所有硬编码的 1password:// URI 替换为 onepassword://。

---

开始之前

你需要准备两项内容：

1. Node.js 20 或更高版本
2. 一个 1Password Service Account，且有权访问你希望 AI 使用的库

创建服务帐户（通俗说明）

1. 在网页上登录你的 1Password 帐户。
2. 打开 Developer → Service Accounts（或参阅 1Password 指南）。
3. 创建服务帐户，并且仅授予它你希望自动化操作访问的库（例如 Automation 或 CI 库——不要授予个人银行账户库）。
4. 复制一次令牌。请像对待主密钥一样妥善保管。

---

快速开始

Claude Desktop / Cursor / VS Code / 大多数 IDE

将以下内容添加到 MCP 配置中（具体文件取决于应用）：

{
  "mcpServers": {
    "1password": {
      "command": "npx",
      "args": ["-y", "@takescake/1password-mcp"],
      "env": {
        "OP_SERVICE_ACCOUNT_TOKEN": "YOUR_SERVICE_ACCOUNT_TOKEN"
      }
    }
  }
}

重启应用，然后试着说：“列出我的 1Password 保管库。”

macOS 钥匙串（配置文件中不存放令牌）

将令牌存储在钥匙串中，然后让服务使用它：

{
  "mcpServers": {
    "1password": {
      "command": "npx",
      "args": ["-y", "@takescake/1password-mcp"],
      "env": {
        "OP_KEYCHAIN_SERVICE": "op-service-account-claude-automation",
        "OP_KEYCHAIN_ACCOUNT": "your-macos-username"
      }
    }
  }
}

令牌解析顺序： CLI（--service-account-token / --token）→ OP_SERVICE_ACCOUNT_TOKEN → macOS 钥匙串。如果服务名称唯一，则 OP_KEYCHAIN_ACCOUNT 可选。请避免使用 CLI 标志：命令行参数对其他本地进程可见，而且如果使用这些标志，服务会在启动时记录警告。

OpenAI Codex（TOML）

选项 A — 在配置中填写令牌：

[mcp_servers."1password"]
command = "npx"
args = ["-y", "@takescake/1password-mcp"]

[mcp_servers."1password".env]
OP_SERVICE_ACCOUNT_TOKEN = "YOUR_SERVICE_ACCOUNT_TOKEN"

选项 B（推荐）— 配置中只指定环境变量：

[mcp_servers."1password"]
command = "npx"
args = ["-y", "@takescake/1password-mcp"]
env_vars = ["OP_SERVICE_ACCOUNT_TOKEN"]

在 shell 或 CI 中设置 OP_SERVICE_ACCOUNT_TOKEN。注意：codex mcp add ... --env OP_SERVICE_ACCOUNT_TOKEN=... 会将密钥写入 Codex 配置；在可行时优先使用 env_vars。

在 macOS 上，可以省略令牌环境变量，改用 OP_KEYCHAIN_SERVICE（以及可选的 OP_KEYCHAIN_ACCOUNT）。

可选：将服务限制为特定保管库

默认情况下，服务可以使用服务账户可见的任何保管库。若要设置允许列表：

{
  "env": {
    "OP_SERVICE_ACCOUNT_TOKEN": "YOUR_SERVICE_ACCOUNT_TOKEN",
    "OP_MCP_ALLOWED_VAULTS": "Automation, CI"
  }
}

名称或 ID 均可（不区分大小写）。也可以通过 --allowed-vaults 设置。允许列表适用于整个服务，会影响所有涉及保管库的工具和资源，而不仅仅是 op_run / op_check_ref：

• vault_list 和 onepassword://vaults 仅显示允许的保管库。
• 接受 vaultId 的工具以及 onepassword://vaults/{vaultId}/items 资源，必须提供保管库 ID（而不是名称）；列表外的保管库会被拒绝。
• op:// 引用会同时按原样检查，并根据其实际解析到的保管库进行检查。
• 设置允许列表后，每次受限调用都会额外读取一次 vaults.list（请注意服务账户的速率限制）；如果无法列出保管库，服务会默认拒绝访问。

从 4.0.3 或更早版本升级？ 如果你设置此项时以为它只会影响 op_run / op_check_ref，现在它会限制所有操作。

这是纵深防御：请先在 1Password 中限制服务账户本身的保管库访问权限。

---

面向 Agent：如何处理密钥

每次都按以下顺序操作：

1. 使用 vault_list → item_lookup / item_list 进行发现（仅获取元数据）。
2. 使用 op_check_ref 确认引用——不要仅为确认路径是否存在而执行 reveal。
3. 使用 op_run 和 env 中的 op://vault/item/field，在命令或 API 调用中使用密钥。
4. 只有当用户明确需要在聊天中看到值时，才使用 password_read / item_get + reveal: true 显示密钥。
5. 使用 password_generate → password_update 轮换密钥（除非用户提出要求，否则保持 returnSecret: false）。
6. 除非需要永久移除，否则优先使用 item_archive，而不是 item_delete。

op_run 示例

{
  "argv": ["curl", "-sS", "https://api.example.com/health"],
  "env": {
    "API_TOKEN": "op://Automation/Example API/credential"
  },
  "timeout_ms": 60000
}

在可行时优先使用 argv，而不是 shell command 字符串——这样更不容易遇到引号问题。

---

配置参考

环境变量

变量	必需	说明
OP_SERVICE_ACCOUNT_TOKEN	通常需要	服务账户令牌。如果已设置钥匙串变量，则 macOS 上不需要。
OP_KEYCHAIN_SERVICE	否	macOS：令牌对应的钥匙串服务名称。
OP_KEYCHAIN_ACCOUNT	否	macOS：可选账户，用于缩小钥匙串查找范围。
OP_MCP_ALLOWED_VAULTS	否	服务可使用的保管库名称/ID（不区分大小写），以逗号分隔；对整个服务生效。留空 = 不受限制。
OP_INTEGRATION_NAME	否	向 1Password SDK 报告的名称（默认值：1password-mcp）。
OP_INTEGRATION_VERSION	否	向 SDK 报告的版本（默认值：包版本）。
MCP_LOG_LEVEL	否	debug | info | warn | error（默认值：info）。
MCP_DEBUG	否	设置后强制启用调试日志。

CLI 标志

--service-account-token <token>   1Password service account token (avoid: visible to other local processes)
--token <token>                   Alias for --service-account-token
--log-level <level>               error | warn | info | debug (default: info)
--integration-name <name>         Custom integration name for the 1Password SDK
--integration-version <version>   Custom integration version
--allowed-vaults <list>           Comma-separated vault allow-list (names or IDs), applied server-wide

---

安全与隐私

在将服务指向你在意的保管库之前，请先阅读此内容。

• LLM 隐私 — 向模型透露的任何内容都可能发送给你的 AI 提供商，并根据其政策留存。
• MCP 不会对传输中的机密进行端到端加密 — 在 MCP 工作流中以及传递给模型时，值均为明文。存储后，值会在 1Password 中静态加密。
• 最适用场景 — 自动化凭据：CI 令牌、机器人账户、临时环境机密。
• 避免存放 — 银行信息、主要个人登录凭据、恢复码，或任何你无法承受暴露给模型提供商的内容。
• 令牌 = 主密钥 — 严格限制服务账户的权限；若令牌泄露，立即轮换；切勿提交令牌或包含机密的 MCP 配置。
• 优先使用环境变量或 Keychain 存放令牌 — --token / --service-account-token 会将令牌放在进程参数中，其他本地进程可以读取这些参数（服务会在启动时发出警告）。相同用户的进程通常也能读取服务的环境变量（例如 Linux 上的 /proc/<pid>/environ），因此在 macOS 上，Keychain 是最安全的选择：它能让令牌避开配置文件和进程环境。
• 优先使用引用 — 使用 op://… + op_run，胜过将密码粘贴到提示词或文件中。
• op_run 会以你的用户身份运行任意命令 — 请为其保留 MCP 客户端的审批提示；不要自动批准。
• 脱敏尽力而为 — op_run 会在返回的输出中屏蔽解析出的机密，包括常见编码形式（base64、JSON 和 URL 编码形式、多行值）。这有助于防止意外泄露，但它不是沙箱：命令可以故意转换或传输它获得的机密。
• 备注不会隐藏 — item_get 会原样返回备注（与 op item get 一样）。不要在 Agent 可读取的保管库备注中存放机密。
• 最小权限原则 — 专用自动化保管库胜过共享整个账户。OP_MCP_ALLOWED_VAULTS 是第二道防线，不能取代权限限制。
• 报告漏洞 — 请提交公开 issue；参见 SECURITY.md。

---

协议与兼容性

组成部分	详情
软件包	@takescake/1password-mcp
运行时	Node.js ≥ 20
传输方式	stdio
MCP SDK	@modelcontextprotocol/server v2
协议	协商 2026-07-28；保持对旧版客户端的兼容性
注册表名称	io.github.CakeRepository/1password

---

开发

git clone https://github.com/CakeRepository/1Password-MCP.git
cd 1Password-MCP
npm ci
npm run build
npm test
npm run lint

监视模式：npm run dev。

项目布局

src/
  index.ts                 # Entrypoint — MCP stdio + protocol negotiation
  server.ts                # buildServer() — registers tools, prompts, resources
  config.ts                # CLI / env / Keychain / allow-list
  client.ts                # 1Password SDK client
  logger.ts                # Structured logs on stderr (stdout is protocol)
  secret-ref.ts            # op:// parsing & reference checks
  vault-access.ts          # Server-wide vault allow-list enforcement
  redaction.ts             # op_run output redaction
  utils.ts                 # Result helpers, password generation
  tools/                   # All 15 MCP tools
  prompts/                 # Interactive workflow prompts
  resources/               # onepassword:// resources
tests/

参见 CONTRIBUTING.md。维护者 / Agent：参见 agents.md。

---

更新日志

版本历史参见 CHANGELOG.md，其中包括 5.0.0 版本（资源 URI 从 1password:// 改为 onepassword://，并加强了安全性；升级前请阅读 Changed 说明）、4.0.0 版本的 MCP v2 / 2026-07-28 迁移，以及 3.0.0 版本对 op_run / 显示机密需显式授权的安全变更。

---

许可证

Apache License 2.0