{
  "markdown": "# 1Password MCP Server\n\n[![CI](https://github.com/CakeRepository/1Password-MCP/actions/workflows/ci.yml/badge.svg)](https://github.com/CakeRepository/1Password-MCP/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/@takescake/1password-mcp?color=cb3837)](https://www.npmjs.com/package/@takescake/1password-mcp)\n[![Node](https://img.shields.io/node/v/@takescake/1password-mcp)](https://www.npmjs.com/package/@takescake/1password-mcp)\n[![MCP](https://img.shields.io/badge/MCP-2026--07--28-0ea5e9)](https://modelcontextprotocol.io/specification/2026-07-28)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)\n\n**Give your AI assistant a locked door to 1Password — not a pile of passwords in the chat.**\n\n`@takescake/1password-mcp` is a community [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server. It lets Claude, Cursor, VS Code Copilot, OpenAI Codex, Gemini, and other MCP clients manage vaults and credentials through a [1Password Service Account](https://developer.1password.com/docs/service-accounts/).\n\nBuilt 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.\n\n> **Not an official 1Password product.** Community-built, Apache 2.0 licensed.\n\n---\n\n## Who this is for\n\n| You are… | You get… |\n|----------|----------|\n| **Not deeply technical** | A one-time setup: create a service account, paste the token into your AI app’s MCP settings, then ask in plain English (“list my automation vault”, “rotate the staging DB password”). |\n| **An agent / LLM** | Fifteen typed tools, four workflow prompts, three browsable resources, and clear rules: **prefer `op_run` + `op://` over revealing secrets**. |\n| **A developer / SRE** | Full item CRUD, secure notes, password generation, vault allow-lists, Keychain token loading on macOS, and CI-friendly env config. |\n\n---\n\n## Why teams pick this server\n\n- **Security-first defaults** — `password_read` and `item_get` return metadata unless you opt in with `reveal: true`.\n- **`op_run` (the MCP equivalent of `op run`)** — inject `op://vault/item/field` into a local command’s environment; plaintext is redacted from stdout/stderr and never logged back to the model.\n- **Full vault toolkit** — list, search, get, edit, create logins & notes, rotate passwords, archive, or delete.\n- **Guided prompts** — password generation, credential rotation, vault audit, and secret-reference helpers.\n- **Browsable resources** — vault and item catalogs over `1password://…` URIs (no secrets in resource payloads).\n- **Modern MCP** — stdio transport, Zod 4 schemas, MCP 2026-07-28 negotiation with legacy client compatibility.\n\n---\n\n## What you get\n\n### Tools (15)\n\nGrouped the way agents and humans actually use them.\n\n#### Discover\n\n| Tool | What it does |\n|------|----------------|\n| `vault_list` | List vaults the service account can access (id, name, description, type). |\n| `item_lookup` | Search a vault by title substring; optional `limit` (max 200). |\n| `item_list` | List every item in a vault (id, title, category, tags, `updatedAt`) — never secrets. |\n\n#### Read (safe by default)\n\n| Tool | What it does |\n|------|----------------|\n| `item_get` | Full item: title, category, tags, notes, fields. Concealed values stay hidden unless `reveal: true`. Accepts `op://…` **or** `vaultId` + `itemId`. |\n| `password_read` | Read one field (default `password`) via `op://…` or ids. **Metadata-only unless `reveal: true`.** Prefer `op_run` to *use* a secret. |\n| `op_check_ref` | Validate `op://vault/item/field` and return non-secret metadata only (vault, item, field). Never the value. |\n\n#### Create & update\n\n| Tool | What it does |\n|------|----------------|\n| `password_create` | Create a Login or Password item (username, URL, tags, notes). `returnSecret` defaults to `false`. |\n| `note_create` | Create a Secure Note with optional tags and custom fields. |\n| `password_update` | Rotate a password / concealed field (creates the field if missing). |\n| `item_edit` | Update title, notes (empty string clears), tags, URL; upsert or remove fields. Unreferenced fields stay untouched. |\n| `password_generate` | Cryptographically secure random password (length 8–128; symbols/numbers/uppercase toggles). |\n| `password_generate_memorable` | Memorable passphrase from a ~500-word list (word count, separator, number/symbol suffixes). |\n\n#### Use secrets without revealing them\n\n| Tool | What it does |\n|------|----------------|\n| `op_run` | Run a local command (`command` **or** `argv`) with env vars. Values matching `op://…` are resolved into the **child process only**; resolved secrets are redacted from returned output. Optional `cwd`, `shell`, `timeout_ms`, `stdin`. |\n\n#### Soft-delete & destroy\n\n| Tool | What it does |\n|------|----------------|\n| `item_archive` | Move an item to the archive (hidden from normal views). |\n| `item_delete` | Permanently delete an item — **cannot be undone**. |\n\n### Prompts (4)\n\n| Prompt | When to use it |\n|--------|----------------|\n| `generate-secure-password` | Generate (random or memorable) and optionally store — without dumping the password into chat. |\n| `credential-rotation` | Find → verify access → generate → update → confirm `op://` reference. |\n| `vault-audit` | Inventory a vault by category; flag duplicates / oddities — never reveal secrets. |\n| `secret-reference-helper` | Build a paste-ready `op://vault/item/field` from names. |\n\n### Resources (3)\n\n| URI | Contents |\n|-----|----------|\n| `1password://config` | Non-secret server config (name, version, log level, token source, Node version). |\n| `1password://vaults` | JSON list of accessible vaults. |\n| `1password://vaults/{vaultId}/items` | JSON item metadata for one vault (no secret values). |\n\n---\n\n## Before you start\n\nYou need two things:\n\n1. **Node.js 20 or newer**\n2. A **1Password Service Account** with access to the vault(s) you want the AI to use\n\n### Create a service account (plain English)\n\n1. Sign in to your 1Password account on the web.\n2. Open **Developer** → **Service Accounts** (or follow [1Password’s guide](https://developer.1password.com/docs/service-accounts/)).\n3. 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).\n4. Copy the token once. Treat it like a master key.\n\n---\n\n## Quick start\n\n### Claude Desktop / Cursor / VS Code / most IDEs\n\nAdd this to your MCP config (exact file depends on the app):\n\n```json\n{\n  \"mcpServers\": {\n    \"1password\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@takescake/1password-mcp\"],\n      \"env\": {\n        \"OP_SERVICE_ACCOUNT_TOKEN\": \"YOUR_SERVICE_ACCOUNT_TOKEN\"\n      }\n    }\n  }\n}\n```\n\nRestart the app, then try: *“List my 1Password vaults.”*\n\n### macOS Keychain (no token in the config file)\n\nStore the token in Keychain, then point the server at it:\n\n```json\n{\n  \"mcpServers\": {\n    \"1password\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@takescake/1password-mcp\"],\n      \"env\": {\n        \"OP_KEYCHAIN_SERVICE\": \"op-service-account-claude-automation\",\n        \"OP_KEYCHAIN_ACCOUNT\": \"your-macos-username\"\n      }\n    }\n  }\n}\n```\n\n**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.\n\n### OpenAI Codex (TOML)\n\n**Option A** — token in config:\n\n```toml\n[mcp_servers.\"1password\"]\ncommand = \"npx\"\nargs = [\"-y\", \"@takescake/1password-mcp\"]\n\n[mcp_servers.\"1password\".env]\nOP_SERVICE_ACCOUNT_TOKEN = \"YOUR_SERVICE_ACCOUNT_TOKEN\"\n```\n\n**Option B** *(recommended)* — config only names the env var:\n\n```toml\n[mcp_servers.\"1password\"]\ncommand = \"npx\"\nargs = [\"-y\", \"@takescake/1password-mcp\"]\nenv_vars = [\"OP_SERVICE_ACCOUNT_TOKEN\"]\n```\n\nSet `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.\n\nOn macOS you can omit the token env and use `OP_KEYCHAIN_SERVICE` (+ optional `OP_KEYCHAIN_ACCOUNT`) instead.\n\n### Optional: lock `op_run` / `op_check_ref` to certain vaults\n\nBy default those tools may resolve `op://` references from any vault the service account can see. To allow-list vaults:\n\n```json\n{\n  \"env\": {\n    \"OP_SERVICE_ACCOUNT_TOKEN\": \"YOUR_SERVICE_ACCOUNT_TOKEN\",\n    \"OP_MCP_ALLOWED_VAULTS\": \"Automation, CI\"\n  }\n}\n```\n\nNames or IDs work. References outside the list are rejected before resolution. Same setting via `--allowed-vaults`.\n\n---\n\n## For agents: how to handle secrets\n\nFollow this order every time:\n\n1. **Discover** with `vault_list` → `item_lookup` / `item_list` (metadata only).\n2. **Confirm a reference** with `op_check_ref` — never `reveal` just to see if a path exists.\n3. **Use** a secret in a command or API call with **`op_run`** and `op://vault/item/field` in `env`.\n4. **Reveal** with `password_read` / `item_get` + `reveal: true` only when the human explicitly needs the value in chat.\n5. **Rotate** with `password_generate` → `password_update` (keep `returnSecret: false` unless asked).\n6. Prefer **`item_archive`** over **`item_delete`** unless permanent removal is required.\n\n### `op_run` sketch\n\n```json\n{\n  \"argv\": [\"curl\", \"-sS\", \"https://api.example.com/health\"],\n  \"env\": {\n    \"API_TOKEN\": \"op://Automation/Example API/credential\"\n  },\n  \"timeout_ms\": 60000\n}\n```\n\nPrefer `argv` over a shell `command` string when you can — fewer quoting surprises.\n\n---\n\n## Configuration reference\n\n### Environment variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `OP_SERVICE_ACCOUNT_TOKEN` | Usually yes | Service account token. Not required on macOS if Keychain vars are set. |\n| `OP_KEYCHAIN_SERVICE` | No | macOS: Keychain service name for the token. |\n| `OP_KEYCHAIN_ACCOUNT` | No | macOS: optional account to narrow the Keychain lookup. |\n| `OP_MCP_ALLOWED_VAULTS` | No | Comma-separated vault names/IDs allowed for `op_run` / `op_check_ref`. Empty = unrestricted. |\n| `OP_INTEGRATION_NAME` | No | Name reported to the 1Password SDK (default: `1password-mcp`). |\n| `OP_INTEGRATION_VERSION` | No | Version reported to the SDK (default: package version). |\n| `MCP_LOG_LEVEL` | No | `debug` \\| `info` \\| `warn` \\| `error` (default: `info`). |\n| `MCP_DEBUG` | No | If set, forces debug logging. |\n\n### CLI flags\n\n```\n--service-account-token <token>   1Password service account token\n--token <token>                   Alias for --service-account-token\n--log-level <level>               error | warn | info | debug (default: info)\n--integration-name <name>         Custom integration name for the 1Password SDK\n--integration-version <version>   Custom integration version\n--allowed-vaults <list>           Comma-separated allow-list for op_run / op_check_ref\n```\n\n---\n\n## Security & privacy\n\n> **Read this before pointing the server at a vault you care about.**\n\n- **LLM privacy** — Anything revealed to the model may be sent to your AI provider and retained under their policies.\n- **MCP is not end-to-end encrypted for secrets in flight** — Values are plaintext inside the MCP workflow and toward the model. They are encrypted at rest in 1Password once stored.\n- **Best fit** — Automation credentials: CI tokens, bot accounts, disposable env secrets.\n- **Avoid** — Banking, primary personal logins, recovery codes, or anything you cannot afford to expose to a model provider.\n- **Token = master key** — Scope the service account tightly; rotate immediately if leaked; never commit tokens or MCP configs with secrets.\n- **Prefer references** — `op://…` + `op_run` beat pasting passwords into prompts or files.\n- **Least privilege** — Dedicated automation vaults beat sharing your whole account.\n\n---\n\n## Protocol & compatibility\n\n| Piece | Detail |\n|-------|--------|\n| Package | `@takescake/1password-mcp` |\n| Runtime | Node.js **≥ 20** |\n| Transport | **stdio** |\n| MCP SDK | `@modelcontextprotocol/server` v2 |\n| Protocol | Negotiates **2026-07-28**; keeps legacy client compatibility |\n| Registry name | `io.github.CakeRepository/1password` |\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/CakeRepository/1Password-MCP.git\ncd 1Password-MCP\nnpm ci\nnpm run build\nnpm test\nnpm run lint\n```\n\nWatch mode: `npm run dev`.\n\n### Project layout\n\n```\nsrc/\n  index.ts                 # Entrypoint — MCP stdio + protocol negotiation\n  config.ts                # CLI / env / Keychain / allow-list\n  client.ts                # 1Password SDK client\n  logger.ts                # Structured logs on stderr (stdout is protocol)\n  secret-ref.ts            # op:// parsing & allow-list checks\n  utils.ts                 # Result helpers, password generation\n  tools/                   # All 15 MCP tools\n  prompts/                 # Interactive workflow prompts\n  resources/               # 1password:// resources\ntests/\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Maintainers / agents: [AGENTS.md](AGENTS.md).\n\n---\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history, including the **4.0.0** MCP v2 / 2026-07-28 migration and the **3.0.0** `op_run` / reveal-opt-in security changes.\n\n---\n\n## License\n\n[Apache License 2.0](LICENSE)\n",
  "bytes": 13394,
  "sha": "6a745459113f40e4932e61a2c73d78ca11341bca691b90ef94222d3c729985a1",
  "repo_slug": "cakerepository/1password-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_cakerepository_1password_cc0955df/readme"
}