onepassword-agent-mcp

1Password Agent MCP

让 AI Agent 通过本地 MCP 服务使用和保存 1Password 密钥，并通过控制面板让你掌控全局。

• **使用已批准的密钥：**Agent 会收到加密句柄。服务会在本地解析所选字段并复制或粘贴，不会将明文返回给 Agent。
• **保存已复制的密钥：**在浏览器或本地应用中复制密码或 API 密钥，然后让服务通过仅包含元数据的工具参数将其保存到 1Password。
• **无人值守运行：**可选择为新条目启用自动批准，并连接范围受限的 1Password 服务帐户，避免反复解锁桌面应用。

npm 包 · 设置指南 · 用户指南 · 安全模型 · 卸载指南

独立项目。与 1Password 无关联，也未获其认可。每次安装都使用独立的本地设置和 1Password 帐户。

当前控制面板，使用合成示例条目呈现。本 README 中的所有截图均使用演示数据；未显示任何真实帐户、密码或服务帐户令牌。打开完整尺寸的保险库截图。

快速开始

你需要 Node.js 20+、1Password CLI（op），以及支持本地 stdio 服务的 MCP 客户端。可通过 1Password 桌面集成或范围受限的服务帐户进行身份验证。

在 macOS 上，如有需要，请安装前置条件：

brew install node 1password-cli

如需通过桌面授权，请打开 1Password → 设置 → 开发者，并启用 与 1Password CLI 集成。仅批准你信任的客户端。服务帐户设置请参阅无人值守访问。

安装并运行引导安装程序：

npm install -g onepassword-agent-mcp
onepassword-agent-mcp install

安装程序会检测受支持的 MCP 客户端，并在更新其配置前征求同意。在 macOS 上，程序还会单独提供可选的可见菜单栏快捷方式。

启动控制面板：

onepassword-agent-mcp admin

打开 http://127.0.0.1:7319。如需手动设置，请运行 onepassword-agent-mcp doctor，然后运行 onepassword-agent-mcp setup all --apply。

**要更新现有安装？**运行 npm install -g onepassword-agent-mcp@latest，然后重启管理控制台和现有 MCP 客户端，使其使用新代码。本地设置、批准记录和加密密钥都会保留。

控制面板

侧边栏将日常任务分为四项：

为 Agent 提供第一个凭据

1. 打开 Vault。在 Agent Vault Setup 下，如果专用保险库尚不存在，请选择 Create MCPVAULT。
2. 在 Choose From 1Password 中，选择一个 Source vault，搜索条目，然后点击 Copy。你也可以将其拖到 Approve Agent Items 中，然后选择 Copy 或 Move。
3. 在 Approve Agent Items 中，点击 Review Details。选择要允许使用的确切字段，并输入 Agent 可以使用这些字段的网站。
4. 点击 Approve Selected。已批准的字段会显示在 Allowed For Agents 中；使用其中的 Enabled 开关、Save 和 Delete 控件来管理访问权限。
5. 在 MCP 客户端中，让 Agent 查找适用于当前网站的已批准凭据，并将其粘贴到指定字段中。

Copy 会保留源条目。Move 会在转移后从源保险库中移除该条目。将条目复制到 Agent 保险库并不会自动批准该条目。网站列表为空时，所有网站均可访问；如需限制访问，请添加域名。

类型筛选器——All Fields、Logins、API Keys、Credit Cards、Notes & SSH 和 Other——可让你更轻松地检查较大的保险库。手动批准时，不会自动建议卡片 CVV 和 PIN 等敏感字段。

如要将新保存的凭据转移回其他保险库，请打开 Review Details → Save this item to another vault。Copy To Vault 会保留 Agent 保险库中的条目；Move To Vault 会从 Agent 保险库中移除该条目及其本地审批。包含附件、文档或通行密钥的条目，请使用 1Password 应用处理。

选择 Agent 可以执行的操作

打开 Permissions，选择所需设置，然后点击 Save Settings。以下三个选项在全新安装时均处于关闭状态。

演示配置：三个选择启用的权限均已开启，并显示模拟的已保存服务账户状态。令牌字段为空；已保存的令牌绝不会显示。打开全尺寸权限截图。

Profile 视图是独立的：Agent 可以通过 get_profile_data 读取在此输入的值。请勿将密码或令牌存储为个人资料值。

从浏览器或选中的文本中保存

在 Permissions 中，启用 Allow agents to save new items into MCPVAULT 和 Save secrets from the clipboard，然后点击 Save Settings。如果希望 Agent 能立即使用新项目，也可以启用自动批准。

1. 在浏览器中，点击密钥的 Copy 按钮；或者在本地应用中选中文本并使用 Copy。Agent 执行此操作时，不应读取字段、剪贴板、DOM 值或会暴露密钥的屏幕截图。
2. 仅使用元数据调用本地工具：

{
  "title": "Example account",
  "requestId": "example-signup-unique-id",
  "category": "login",
  "url": "https://example.com",
  "username": "my-login"
}

使用这些参数调用 save_secret_from_clipboard。支持的类别包括 login、password、api_credential 和 secure_note。文本会原样保留，包括空格和换行符。该工具在托管此 MCP 服务的计算机上运行，并读取该计算机的剪贴板；远程浏览器的剪贴板是另一个剪贴板。

应用会在本地加密重试快照，该快照可使用 15 分钟；明文仅通过本地 CLI 的 stdin 传递，并会验证已存储的项目。响应包含保存和批准元数据，不包含复制的文本；对于已批准的加密句柄，请使用查找／列表工具。进程运行期间或停机后下次捕获时，过期密文会被移除；元数据记录会阻止重复使用旧请求 ID。清除剪贴板前会重新检查其值是否已更改，并尽力执行清除；请检查返回的清理状态。剪贴板管理器可能会保留自己的历史记录。

重试时使用相同的 requestId 和元数据。即使剪贴板内容已更改，重试也会使用原始的加密捕获内容。如果捕获内容已过期，操作会安全失败，而不会捕获不相关的文本；有意发起新请求前，请检查之前的操作。标题、用户名和 URL 等元数据对模型仍然可见：切勿将密钥放入这些字段。save_secret_item 仍可用于已在上下文中的值，但无法撤销这些值的暴露。

自动批准

在 Permissions 下，启用 Automatically approve items agents create，然后点击 Save Settings。此选项默认关闭。还必须启用 Agent 项目创建功能。

启用后，通过 save_secret_item 或 save_secret_from_clipboard 验证保存的项目，会在配置的 Agent 保管库中自动批准新项目的所有受支持字段，包括信用卡 CVV 和 PIN。Agent 可立即使用生成的加密句柄。现有项目以及通过管理控制台复制或移入的项目仍需手动批准。

onepassword-agent-mcp settings auto-approve on
onepassword-agent-mcp settings auto-approve off
onepassword-agent-mcp settings --json

Permissions → Unattended access 卡片可直接在本地控制台中接受 1Password 服务帐户令牌。请在 1Password 的服务帐户设置中创建令牌，并仅授予其访问专用 Agent 保管库的权限。授予 read_items，保存项目时还需授予 write_items。在控制台中，将令牌粘贴到 Service account token，然后点击 Save encrypted token。输入内容会立即清空。请勿在聊天中发送令牌。

应用会在本地将令牌加密存储于 ~/.onepassword-mcp/access.json，绝不会将其返回给控制台或 MCP 客户端，并且只会将令牌提供给 CLI 进程环境。更改会应用于后续 CLI 调用，无需重启。Test connection 会检查保管库是否可见；它不会写入测试项目，也不会确认写入权限。关闭 Use saved service account 可切换回桌面身份验证，或者选择 Remove saved token 删除本地凭据。如果要在所有位置使令牌失效，请在 1Password 中撤销该令牌。切换后，正在执行的操作可能仍会完成。

外部配置的 OP_SERVICE_ACCOUNT_TOKEN 优先级更高；控制台会报告当前使用的模式，删除本地令牌无法禁用环境凭据。服务帐户无法访问内置的 Personal/Private/Employee 保管库。启用限定范围的无人值守访问时，控制台只能查看该令牌可访问的保管库；若要从其他桌面帐户保管库复制项目，请先将其禁用。

权限分为三个不同的层级：

此应用不会更改 MCP 客户端的工具调用确认设置，也不会绕过 1Password 的桌面解锁保护。请参阅 1Password 的桌面集成安全模型和服务帐户 CLI 文档。

客户端设置

默认情况下，设置 CLI 会输出一次试运行结果。它会检测已安装的 Claude Code、Claude Desktop、Codex、VS Code、Xcode 编码 Agent 和 Raycast AI：

onepassword-agent-mcp setup all

对所有检测到的客户端应用设置：

onepassword-agent-mcp setup all --apply

该命令使用绝对可执行文件路径，因此 GUI 应用不依赖 Terminal 的 PATH。Claude Desktop 和 VS Code JSON 会与带时间戳的备份合并处理。Xcode 的专用 Codex 和 Claude 配置文件夹会单独处理，因为 Xcode 不使用常规 CLI 配置。

Raycast 将 MCP 配置存储在由应用管理的存储中，且不提供受支持的外部配置写入工具。CLI 会打开 Raycast 官方的 Import Servers 页面；请检查准备好的条目，并在 Raycast 中确认一次。这是唯一需要针对特定客户端进行的交互步骤。

Claude Code

onepassword-agent-mcp setup claude-code --apply

等效命令：

claude mcp add --scope user onepassword-agent-mcp -- onepassword-agent-mcp mcp

Codex

onepassword-agent-mcp setup codex --apply

等效命令：

codex mcp add onepassword-agent-mcp -- onepassword-agent-mcp mcp

VS Code 中的 GitHub Copilot

onepassword-agent-mcp setup copilot --apply

等效的 VS Code 命令：

code --add-mcp '{"name":"onepassword-agent-mcp","command":"onepassword-agent-mcp","args":["mcp"]}'

.vscode/mcp.json 中的工作区备用配置：

{
  "servers": {
    "onepassword-agent-mcp": {
      "type": "stdio",
      "command": "onepassword-agent-mcp",
      "args": ["mcp"]
    }
  }
}

Claude Desktop

onepassword-agent-mcp setup claude-desktop --apply

CLI 会安全地将服务合并到 Claude Desktop 的用户 JSON 中，并保留所有其他设置。

Xcode

onepassword-agent-mcp setup xcode --apply

这会配置仅在 Xcode 内部使用的隔离 Codex 和 Claude Agent 环境。

Raycast AI

onepassword-agent-mcp setup raycast --apply

Raycast 会打开原生导入页面，以供最后确认。默认情况下，Raycast 会在调用 MCP 工具前询问。

ChatGPT Desktop

本地设置中有意不包含 ChatGPT Desktop。目前，ChatGPT 连接的是远程 MCP 服务，而不是任意本地 stdio 命令。请勿仅为连接它而通过公共隧道暴露此密码桥接服务。

其他 MCP 客户端

打印通用 MCP JSON：

onepassword-agent-mcp setup generic --json

通用配置：

{
  "mcpServers": {
    "onepassword-agent-mcp": {
      "command": "onepassword-agent-mcp",
      "args": ["mcp"]
    }
  }
}

运行时与菜单栏

安装 npm 包只会添加命令，不会安装启动代理、守护进程、后台服务、启动项、浏览器扩展或隐藏的常驻进程。

• onepassword-agent-mcp admin 仅在该终端进程运行期间启动本地审批控制台。
• onepassword-agent-mcp mcp 是一个 stdio MCP 服务。Claude Code、Codex 或 VS Code 等 MCP 客户端在需要时会将其作为子进程启动。
• onepassword-agent-mcp setup ... --apply 只会写入 MCP 客户端配置。合并前会备份现有 JSON 文件。
• 只有在你明确选择安装时，才会安装可选的 macOS 菜单栏配套应用。该应用运行时，其图标始终可见。
• 登录时启动是单独的选项，默认关闭。即使启用，可见的菜单栏应用也不会启动管理服务器，除非你选择打开管理控制台。
• 重启电脑不会自动启动此项目，除非你启用了可选的菜单栏登录项，或其他应用启动了 MCP 客户端，而该客户端又启动了 stdio 服务。
• ~/.onepassword-mcp 中的本地状态包括设置、审批、配置文件数据、审计和保存操作元数据、加密密钥、可选的加密服务账户凭据，以及剪贴板重试记录。请参阅本地状态。

你可以随时查看此说明：

onepassword-agent-mcp runtime

可选的 Mac 菜单栏

在 macOS 上，引导式安装程序可以在菜单栏中添加一个标识清晰的 1P 项。你也可以稍后在控制面板的权限 → Mac 菜单栏快捷方式中启用它。

此配套应用由 native/MenuBarApp.swift 中可读的 Swift 源代码在本地构建。npm 包中不包含不透明的应用二进制文件。生成的应用使用项目的青绿色盾牌徽标，安装在 ~/Applications/1Password Agent MCP.app，且绝不会请求管理员权限。

手动控制：

onepassword-agent-mcp menubar status
onepassword-agent-mcp menubar install
onepassword-agent-mcp menubar launch
onepassword-agent-mcp menubar remove
onepassword-agent-mcp menubar install --launch-at-login
onepassword-agent-mcp menubar login on
onepassword-agent-mcp menubar login off
onepassword-agent-mcp menubar uninstall --apply

使用 menubar remove 关闭可见快捷方式，但不卸载它；使用 menubar launch 再次显示。卸载后，使用 menubar install 重新安装。管理控制台运行时，本地管理页面也会在权限 → Mac 菜单栏快捷方式下提供相同的安装控制选项。

菜单中包含打开管理控制台、停止管理控制台、登录时启动菜单栏应用、从菜单栏移除和卸载菜单栏快捷方式。打开管理控制台会在需要时启动控制台，然后打开它，因此无需单独的“启动”操作。从菜单栏移除只会关闭可见的辅助应用；它仍会保留安装状态，并且可以重新打开。卸载菜单栏快捷方式会在确认后移除辅助应用及其登录项。这两种操作都不会更改 MCP 客户端配置、本地审批、MCPVAULT 或 1Password 项目。

管理控制台本身提供明确的进程控制：

onepassword-agent-mcp admin status
onepassword-agent-mcp admin stop

MCP 工具

• onepassword_status：检查 CLI、MCPVAULT、本地审批、个人资料数据和设置。
• find_secrets_for_site：返回某个网站已获批准的加密句柄。
• list_approved_secrets：列出已获批准的句柄和允许访问的网站。
• copy_secret：解析句柄，并将选定字段复制到剪贴板。
• paste_secret：解析句柄、复制内容并粘贴到活动应用中，不返回明文。
• clear_secret_clipboard：清空剪贴板。
• save_secret_item：在启用本地保存设置时，将新的登录信息、密码、API 凭据、安全便笺或信用卡保存到 MCPVAULT。返回验证和审批状态，以及 approvedFields（并返回第一个字段作为兼容用途的 approvedField）。自动审批遵循本地 autoApproveAgentItems 设置。
• save_secret_from_clipboard：使用仅包含元数据的工具参数、加密重试捕获、验证和可选自动审批，保存本地复制的原文。需要同时拥有剪贴板保存和项目创建权限。
• get_profile_data：返回当前网站允许访问的用户自定义个人资料数据。
• find_passwords_for_site、list_approved_passwords、copy_password、paste_password 和 clear_password_clipboard：兼容性别名。
• admin_ui_info：返回审批控制台 URL。

保存验证和重试

save_secret_item 会报告 created、verified、itemId、vaultId 和 operationId。成功需要回读并确认标题、类别、目标位置、网站和字段值均与预期一致。机密值会在本地进行比较，绝不会包含在结果中。可选的 approvalStatus 是独立状态：项目可以已保存并通过验证，但仍需在管理 UI 中审批。

如果保存过程中断，请使用相同的 requestId 和输入重试。若未提供 requestId，则会对同一目标位置中内容相同的项目进行去重。只有在有意创建另一个项目时，才提供新的 requestId。恢复流程使用唯一的 opmcp-… 项目标记和本地操作记录，绝不会按标题匹配。如果无法协调先前的操作，工具会报告未解决结果，而不会悄悄创建另一个项目。用户撤销的审批绝不会通过保存重试恢复。

在 macOS 和 Linux 上，JSON 通过操作系统管道传输，不会生成明文临时文件，机密值也不会出现在命令参数中。运行器会保留终端会话以进行 1Password 授权，并在超时或取消时清理其子进程组。复制操作会读取并验证受支持的 JSON 字段，包括隐藏值。包含附件、文档或通行密钥的项目必须使用 1Password 应用复制。

更新后，请重启现有 MCP 客户端和管理控制台，确保所有写入操作都使用当前的策略锁定和保存验证代码。现有设置、审批和加密密钥都会保留。

安全模型

受保护的内容：

• 已保存条目的机密信息保留在 1Password 中。剪贴板保存会使用临时加密的重试捕获内容；可选的无人值守服务账户令牌会在本地加密。
• MCP 复制/粘贴工具绝不会返回 1Password 机密字段的明文。
• 句柄和存储的 1Password 机密引用会在本地加密。
• 禁用或删除审批后，旧句柄会失效。
• 复制和粘贴时都会重新检查允许的网站。
• MCP 服务仅列出并解析已配置的 Agent 保管库中的审批。
• 由 Agent 创建的条目和剪贴板捕获是单独的可选项；新条目只会保存到已配置的 Agent 保管库。
• 自动审批 Agent 创建的字段是单独的可选设置，默认关闭。

仍然敏感的内容：

• 操作系统剪贴板会短暂包含字段值明文。
• 触发粘贴时，当前活动应用会收到字段值。
• 可访问剪贴板的本地进程可能会监视复制的机密信息。
• 加密密钥位于同一用户账户的本地。能够同时读取密钥和加密文件的进程可以解密这些文件。
• 使用桌面 CLI 集成时，本地 1Password CLI 会话对保管库的访问权限可能比 MCP 暴露的权限更广。
• get_profile_data 会返回你在管理界面中明确添加的个人资料值明文。

如需最严格的安全边界，请使用仅限于 MCPVAULT 的 1Password 服务账户。

将其用于具有强大浏览器控制能力的 Agent 前，请阅读 docs/SECURITY.md。

本地状态

默认状态目录为 ~/.onepassword-mcp：

已保存条目的机密信息保存在 1Password 中。上述加密捕获内容和服务账户凭据是本地存储的例外。这是本地加密，无法防止能够同时读取密文和密钥的进程访问数据。

使用其他状态目录：

ONEPASSWORD_MCP_HOME=/path/to/state onepassword-agent-mcp admin

为新配置使用其他 Agent 保管库名称：

MCP_VAULT_NAME=AgentVault onepassword-agent-mcp admin

对于现有安装，请更改 权限 → 高级本地设置 → Agent 保管库名称 并保存。请确保管理控制台和 MCP 客户端使用相同的状态目录。

对于无头部署，请在 MCP 服务的环境中安全地提供 OP_SERVICE_ACCOUNT_TOKEN。环境令牌的优先级高于仪表板中保存的令牌。请勿将令牌提交到源代码管理中，也不要将其粘贴到 Agent 对话中。

停止并卸载

在运行以下命令的终端中按 Ctrl-C，停止本地审批控制台：

onepassword-agent-mcp admin

断开 MCP 客户端：

onepassword-agent-mcp uninstall all
onepassword-agent-mcp uninstall all --apply

卸载命令会从 Claude Code、Claude Desktop、Codex、VS Code 和 Xcode 中移除相应条目（如果存在），然后移除可选的菜单栏应用／登录项。对于 Raycast，命令会打开 管理服务器，以便手动移除，因为其设置由应用管理。其他客户端设置和所有 1Password 数据均不会受到影响。

可选：删除此应用的本地状态，包括审批、配置文件数据、设置、加密密钥、已保存的服务账户令牌和剪贴板重试记录：

onepassword-agent-mcp uninstall state
onepassword-agent-mcp uninstall state --apply

这会删除 ~/.onepassword-mcp。此操作不会删除 1Password 保管库或项目，也不会撤销 1Password 中的服务账户令牌。只有在确实想删除该保管库时，才在 1Password 中删除 MCPVAULT。

最后，在完成任何可选的状态清理后，移除全局 npm 软件包：

npm uninstall -g onepassword-agent-mcp

故障排除

运行 onepassword-agent-mcp doctor，检查 CLI 发现、授权、保管库可见性、本地创建权限和控制台运行状态。

开发

克隆并安装：

git clone https://github.com/gambadio/onepassword-agent-mcp.git
cd onepassword-agent-mcp
npm ci

使用 npm run dev:admin 或 npm run dev:mcp 在本地运行。

验证

npm ci
npm run typecheck
npm test
npx playwright install chromium
npm run test:ui
npm run build
node scripts/test-live.mjs

最后一条命令会通过实际 CLI 空运行测试全部五个类别。出现提示时，请解锁 1Password 并授权 CLI 访问。如需进一步测试实际的 MCP 保存、精确回读、 重试去重和复制，请运行：

node scripts/test-live.mjs --create

这需要已保存的 Agent 创建设置。它会在配置的 Agent 保管库中创建带有唯一标记的 合成测试项，验证这些项目，然后将这些确切的测试项移至「最近删除」。它使用隔离的本地策略状态。 如果验证或清理失败，它会打印恢复状态目录并保留该目录以供检查。doctor 会检查 CLI 授权、目标位置 可见性、本地创建权限和控制台运行状态；它不会执行保存／复制验证。

维护者发布流程通过 GitHub Actions 和短期 OIDC 凭据自动完成。请参阅 docs/RELEASING.md；本地 npm publish 和重复的设备授权不属于发布流程的一部分。

许可证

MIT