1Password Plugin for Claude Code

A 1Password plugin for Claude Code, built and maintained by 1Password. It ships two pieces that work together: an agent skill with the complete Developer Environment workflow, and MCP configuration for the 1Password desktop app server. Secret values stay in 1Password — the agent sees secret names and mount paths, not secret contents.

Install the plugin rather than hand-configuring an MCP entry on its own. The bundled 1password-environments skill is the authoritative agent workflow; the MCP server's built-in documentation resources cover tool basics only and omit the import-and-mount steps.

For more on 1Password's developer tools, see the 1Password Developer Documentation.

Requirements

• 1Password subscription
• 1Password desktop app on macOS or Linux
• Claude Code

Additional requirements by feature:

• MCP — Integrate with MCP clients turned on under Settings > Developer in the desktop app. If the checkbox is missing, your account may not have the ai-local-mcp-server feature flag. The plugin's .mcp.json launches the 1password-mcp command from your PATH, as described in the 1Password MCP server documentation.

Platform support: MCP and local .env mounts are supported on macOS and Linux. 1Password Environments has no local .env mounts on Windows.

Installation and Setup

Step 1: Set up your Environments

Before using this plugin, configure your secrets in 1Password:

1. Create one or more Environments in 1Password to store your project secrets.
2. Configure locally mounted .env files for them.

Step 2: Install the plugin

Installing the plugin registers the 1password-environments agent skill and the MCP server configuration together.

From the Claude desktop app or claude.ai: Select Customize > Plugins > Discover, search for 1Password, then select Add. The plugin syncs to Claude Code the next time you start a session signed in to the same Claude account.

In Claude Code, run /plugin afterwards to confirm the plugin is installed and the MCP server is connected.

For local development, point Claude Code at a checkout instead:

claude --plugin-dir /path/to/1password-claude-plugin

Step 3: Enable MCP in 1Password (required for Environment management)

In the 1Password desktop app, go to Settings > Developer and turn on Integrate with MCP clients. The plugin's .mcp.json connects Claude Code to that server after this step.

The plugin registers the MCP command documented by 1Password:

{
  "mcpServers": {
    "1password": {
      "command": "1password-mcp"
    }
  }
}

Install the 1Password desktop app on macOS or Linux so 1password-mcp is available on your PATH. For platform-specific install paths and troubleshooting, see the 1Password MCP server documentation.

Step 4: Allow Claude Code to access 1Password data (macOS 27 Golden Gate)

On macOS 27 Golden Gate, macOS blocks apps from accessing 1Password app data by default and doesn't ask for permission. Until you allow it, the MCP server can't start, and /plugin shows the 1Password MCP server as failed.

1. Open System Settings > Privacy & Security > Files & Folders.
2. Select the app you run Claude Code in: the Claude desktop app, your terminal (like Terminal, iTerm, or Ghostty), or your editor (like Visual Studio Code).
3. Turn on the setting that starts with "Data shared by 1Password". The rest of the name depends on which 1Password apps you've installed.
4. Quit and reopen the app, start a new Claude Code session, and run /plugin to confirm the MCP server is connected.

Features

MCP and agent skill

The plugin connects Claude Code to the local 1Password MCP server and bundles the 1password-environments skill (skills/1password-environments/SKILL.md). Claude reads that skill before calling MCP tools — it defines the complete workflow for importing a plain .env file, appending secrets, and mounting at the source path. The MCP server's built-in docs cover tool basics but omit those import-and-mount steps.

See skills/1password-environments/reference.md for setup, mount problems, and troubleshooting.

Example prompts

• "List my 1Password Environments"
• "Mount my staging Environment as .env in this repo"
• "What secrets are in my production Environment?"
• "Create a new Environment called my-app-dev"
• "Create an Environment from my project .env file"
• "Import .env into 1Password and mount it here"
• "Add a placeholder for my OpenAI API key"

MCP tools

Tools are namespaced mcp__plugin_1password_1password__<tool>.

Tool	Description
authenticate	Authenticate with the 1Password desktop app; returns accountId
list_environments	List Developer Environments for an account
create_environment	Create a new Developer Environment
rename_environment	Rename an existing Developer Environment
list_secrets	List secret names in an Environment (no values)
append_secrets	Add or update Environment secrets
create_local_env_file	Mount an Environment as a local .env file
list_local_env_files	List existing local .env mounts for an Environment

Confirm the MCP server is connected with /plugin after installing the plugin and turning on Integrate with MCP clients in 1Password. On macOS 27 Golden Gate, also complete Step 4.

Plugin Structure

1password-claude-plugin/
├── .claude-plugin/
│   ├── plugin.json                    # Plugin manifest
│   └── marketplace.json               # Marketplace catalog (for distribution)
├── skills/
│   └── 1password-environments/
│       ├── SKILL.md                   # Agent skill for MCP workflows
│       └── reference.md               # Setup, mount problems, troubleshooting
├── .mcp.json                          # MCP server configuration
├── LICENSE
└── README.md

Releasing

Each release gets its own PR. Don't change the version number in feature PRs.

The Anthropic plugin directory tracks the stable branch, not main. It scans every new commit on stable and can publish any commit that passes, so only finished releases go there. Feature, docs, and CI changes merge to main as usual and stay out of the directory until the next release. stable is protected: it changes only through reviewed PRs, and it can't be force-pushed or deleted.

1. Create a release branch from the latest main, named after the new version, and push it:

   git checkout main
   git pull
   git checkout -b release/v0.3.0
   git push -u origin release/v0.3.0

   The Prepare release workflow commits a version bump in .claude-plugin/plugin.json and an empty 0.3.0 section in CHANGELOG.md to the branch, then opens a Release v0.3.0 PR.

2. Wait for the Release v0.3.0 PR to appear (usually under a minute; you can watch the run in the Actions tab), then pull the workflow's commit:

   git pull

   If you pull before the workflow finishes, you won't get its commit, and your next push will be rejected.

3. Open CHANGELOG.md and write what changed under Features, Fixes, or Security. Delete any heading you don't use. The new section includes a comment listing the PRs merged since the last release, to help you remember what went in. Delete the comment when you're done.

4. Commit and push:

   git commit -am "Update changelog for v0.3.0"
   git push

5. Merge the PR into main.

6. Open a PR from main into stable:

   gh pr create --base stable --head main --title "Release v0.3.0 to stable" --body "Publishes v0.3.0 to the plugin directory."

   Merge it with Create a merge commit. Don't squash or rebase: stable has to keep main's history, or the next release PR will conflict.

Merging into stable doesn't ship the release to users right away. The directory scans the new commit, and users get the new version once Anthropic reviews and publishes it. Claude Code only offers an update when the version string changes.

Resources

• 1Password Environments — documentation for 1Password's environment and secrets management
• 1Password Local .env Files — how local .env file mounting works
• 1Password MCP server documentation — MCP setup and troubleshooting
• Claude Code Plugins — how to create and distribute Claude Code plugins

License

MIT — Copyright (c) 2026 1Password