1password

1Password MCP Server

Give your AI assistant a locked door to 1Password — not a pile of passwords in the chat.

@takescake/1password-mcp is a community Model Context Protocol (MCP) server. It lets Claude, Cursor, VS Code Copilot, OpenAI Codex, Gemini, and other MCP clients manage vaults and credentials through a 1Password Service Account.

Built on the MCP TypeScript SDK v2 with protocol negotiation for [2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28) (and legacy clients). Secrets stay in 1Password; agents prefer op:// references and op_run so plaintext never has to land in the model transcript.

Not an official 1Password product. Community-built, Apache 2.0 licensed.

---

Who this is for

---

Why teams pick this server

• Security-first defaults — password_read returns metadata, and item_get hides secret-bearing fields (passwords, SSH keys, OTP seeds, card numbers), unless you opt in with reveal: true.
• `op_run` (the MCP equivalent of `op run`) — inject op://vault/item/field into a local command’s environment; resolved secrets are redacted from the returned stdout/stderr on a best-effort basis (including common encodings).
• Full vault toolkit — list, search, get, edit, create logins & notes, rotate passwords, archive, or delete.
• Guided prompts — password generation, credential rotation, vault audit, and secret-reference helpers.
• Browsable resources — vault and item catalogs over onepassword://… URIs (no secrets in resource payloads).
• Modern MCP — stdio transport, Zod 4 schemas, MCP 2026-07-28 negotiation with legacy client compatibility.

---

What you get

Tools (15)

Grouped the way agents and humans actually use them.

Discover

Read (safe by default)

Create & update

Use secrets without revealing them

Soft-delete & destroy

Prompts (4)

Resources (3)

Upgrading from 4.x: resource URIs used to start with 1password://, which MCP clients could never read (a URI scheme can't start with a digit). Replace any hard-coded 1password:// URIs with onepassword://.

---

Before you start

You need two things:

1. Node.js 20 or newer
2. A 1Password Service Account with access to the vault(s) you want the AI to use

Create a service account (plain English)

1. Sign in to your 1Password account on the web.
2. Open Developer → Service Accounts (or follow 1Password’s guide).
3. Create a service account and grant it only the vaults you want automation to touch (for example an Automation or CI vault — not your personal banking vault).
4. Copy the token once. Treat it like a master key.

---

Quick start

Claude Desktop / Cursor / VS Code / most IDEs

Add this to your MCP config (exact file depends on the app):

{

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

Restart the app, then try: *“List my 1Password vaults.”*

macOS Keychain (no token in the config file)

Store the token in Keychain, then point the server at it:

{

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

Token resolution order: CLI (--service-account-token / --token) → OP_SERVICE_ACCOUNT_TOKEN → macOS Keychain. OP_KEYCHAIN_ACCOUNT is optional when the service name alone is unique. Avoid the CLI flags: command-line arguments are visible to other local processes, and the server logs a warning at startup if you use them.

OpenAI Codex (TOML)

Option A — token in config:

[mcp_servers."1password"]

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

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

Option B *(recommended)* — config only names the env var:

[mcp_servers."1password"]

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

Set OP_SERVICE_ACCOUNT_TOKEN in your shell or CI. Note: codex mcp add ... --env OP_SERVICE_ACCOUNT_TOKEN=... writes the secret into Codex config; prefer env_vars when you can.

On macOS you can omit the token env and use OP_KEYCHAIN_SERVICE (+ optional OP_KEYCHAIN_ACCOUNT) instead.

Optional: restrict the server to certain vaults

By default the server can use any vault the service account can see. To allow-list vaults:

{

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

Names or IDs work (case-insensitive). Same setting via --allowed-vaults. The allow-list applies server-wide, to every tool and resource that touches a vault, not only op_run / op_check_ref:

• vault_list and onepassword://vaults show only allowed vaults.
• Tools that take a vaultId, and the onepassword://vaults/{vaultId}/items resource, must be given the vault’s ID (not its name); vaults outside the list are rejected.
• op:// references are checked both as written and by the vault they actually resolve to.
• When an allow-list is set, each guarded call makes one extra vaults.list read (mind service-account rate limits), and the server fails closed if vaults can’t be listed.

Upgrading from 4.0.3 or earlier? If you set this expecting it to affect only op_run / op_check_ref, it now restricts everything.

This is defense in depth: scope the service account’s own vault access in 1Password first.

---

For agents: how to handle secrets

Follow this order every time:

1. Discover with vault_list → item_lookup / item_list (metadata only).
2. Confirm a reference with op_check_ref — never reveal just to see if a path exists.
3. Use a secret in a command or API call with `op_run` and op://vault/item/field in env.
4. Reveal with password_read / item_get + reveal: true only when the human explicitly needs the value in chat.
5. Rotate with password_generate → password_update (keep returnSecret: false unless asked).
6. Prefer `item_archive` over `item_delete` unless permanent removal is required.

op_run sketch

{

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

Prefer argv over a shell command string when you can — fewer quoting surprises.

---

Configuration reference

Environment variables

| OP_INTEGRATION_NAME | No | Name reported to the 1Password SDK (def