1pass-item-mcp

A small, bounded MCP server that lets an AI agent (Claude Code, or any MCP client) use individual 1Password items, one approved command at a time, without ever seeing the secret.

• Explicit allowlist. Only items listed in your config exist for the agent. Each item is pinned to the environment variable it goes into and the only commands that may receive it.

• Approval on every use. The run tool is marked anthropic/requiresUserInteraction, so Claude Code asks you on every call, in every permission mode, with no "don't ask again". The 1Password app asks too, whenever its authorization has expired.

• Never the value. The secret goes into the child process environment only. The agent gets exit code and output, with the secret (and common encodings of it) masked.

• No shell, ever. Commands run as an argv list. Shells, interpreters, file readers, encoders and generic network tools can't be allowlisted.

Not affiliated with or endorsed by 1Password / AgileBits.

agent ──run_with_items(items=["github"], command=["gh","api","user"], reason="…")──►
          Claude Code: approve? (every call)
                          │ yes
        policy: item allowlisted? command allowed for it? args prefix? max_uses?
                binary unchanged since startup?
                          │ ok
        1Password: resolve op://Dev/GitHub PAT/token   (1Password app prompt if needed)
                          │
        exec gh api user  with GH_TOKEN=<secret>   (no shell, own process group, timeout)
                          │
◄── exit code + stdout/stderr, secret masked, size-capped ── audit log (no secrets)

Requirements

• macOS or Linux, Python 3.10+ (uv recommended)

• 1Password desktop app with Settings → Developer → Integrate with other apps enabled (for the default desktop backend). Alternatively a service account or the op CLI.

• python3 on PATH for the Claude Code plugin's guard hook

Related MCP server: sandbox

Install

Claude Code plugin (recommended)

/plugin marketplace add vdoflip/1pass-item-mcp
/plugin install 1pass-item-mcp@1pass-item-mcp

The plugin starts the server with uvx (pinned to a release tag) and adds a guard hook (see Guard hook).

Any MCP client

uvx --from git+https://github.com/vdoflip/1pass-item-mcp@v0.1.0 1pass-item-mcp serve
# or, once published to PyPI:  uvx 1pass-item-mcp serve

{
  "mcpServers": {
    "1pass-item": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/vdoflip/1pass-item-mcp@v0.1.0", "1pass-item-mcp", "serve"]
    }
  }
}

Clients other than Claude Code may ignore requiresUserInteraction. Configure them to require approval for run_with_items.

Configure

1pass-item-mcp init       # writes ~/.config/1pass-item-mcp/config.toml (mode 600)
$EDITOR ~/.config/1pass-item-mcp/config.toml
1pass-item-mcp check      # validates config, resolves and pins commands
1pass-item-mcp check --resolve github   # test-fetch one item (value is not shown)

[onepassword]
backend = "desktop"            # desktop | service-account | cli
account = "my.1password.com"   # as shown in the 1Password app

[limits]
default_timeout_seconds = 60
max_timeout_seconds = 300
max_output_bytes = 65536
max_items_per_call = 5

[audit]
enabled = true                 # ~/.local/state/1pass-item-mcp/audit.jsonl

[items.github]
description = "GitHub token (read-only scopes) for the gh CLI"
ref = "op://Development/GitHub PAT/token"
env = "GH_TOKEN"
commands = ["gh"]
args_prefixes = [["api", "repos/"], ["pr", "view"], ["run", "list"]]
max_uses = 20

The config file and its directory must be owned by you and not group/world-writable. The server reads them once at startup. Restart the MCP server after editing.

Backends

Tools

Guard hook (Claude Code plugin)

The plugin adds a PreToolUse hook so the MCP server stays the only route to 1Password:

• Bash commands using the op CLI (also via full paths, env, sh -c, Python subprocess, …), op:// references, 1Password SDKs or tokens are denied

• running 1pass-item-mcp from the shell is denied (it can't be used to start a second server with a different config)

• writes to the config file/directory or to the installed plugin are denied

Security model

Protects against: an agent (or a prompt injection) reading secrets into its context, widening its own access, using items for commands you didn't intend, or running a swapped-out binary. Each use is approved by a person, and every request is logged locally.

Does not protect against:

• The allowlisted program itself. Whatever you allowlist receives the secret. If it can print its environment, read arbitrary files (/proc/self/environ), send data to arbitrary hosts, or run plugins/extensions/aliases, the agent could get the secret through it. Prefer narrow CLIs and use args_prefixes (e.g. gh without extension, alias, or api to arbitrary hosts).

• Masking is best effort. Literal, base64 (any alignment), hex, URL, JSON-escaped and reversed forms are masked. Arbitrary transformations are not. The command allowlist is the real boundary.

• Same-user processes. The agent runs as you. The guard hook matches command text and can be evaded by obfuscation; the 1Password app prompt and per-call approval remain.

• Output you approve. Command output (minus the secret) goes to the model.

• Python memory hygiene. Secrets are dropped after use but can't be zeroed in Python.

See SECURITY.md to report a vulnerability.

Development

uv sync                 # creates .venv with dev dependencies
uv run pytest           # tests use fake 1Password backends; no account needed
uv run ruff check . && uv run ruff format --check . && uv run mypy

Releases: bump the version in pyproject.toml, src/onepass_item_mcp/__init__.py, claude-plugin/.claude-plugin/plugin.json and the tag in claude-plugin/.mcp.json (a test checks they agree), update CHANGELOG.md, then push a vX.Y.Z tag. The release workflow builds, publishes to PyPI (trusted publishing, pypi environment) and creates a GitHub release.

License

MIT © vdoflip