Use Claude Code with 1Password Environments

The 1Password plugin for Claude Code connects 1Password Environments to Claude Code . The plugin includes:

• An MCP configuration for the 1Password MCP server, which allows Claude Code to manage your Environments with secure authorization prompts.
• An agent skill that supplies Claude Code with end-to-end workflows for interacting with 1Password Environments.
• A hook that runs before Claude Code executes shell commands to confirm your locally mounted .env files are set up correctly.

​

Requirements

• 1Password subscription
• 1Password for Mac, Windows, or Linux
• Claude Code
• sqlite3 installed and available in your PATH, for the validation hook. It’s pre-installed on Mac, and available through your package manager on Linux.

​

Step 1: Set up your Environments

Before you get started, you can set up the Environments that Claude Code will interact with.

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

You can also wait and use the plugin to import your existing .env file and mount a local .env file destination on your behalf.

​

Step 2: Install the plugin

The 1Password plugin is distributed from its GitHub repository . To install the plugin:

1. Open your terminal, go to your project directory, then enter claude to start a Claude Code session.
2. Add the 1Password marketplace:
   /plugin marketplace add 1Password/1password-claude-plugin
   
3. Install the plugin:
   /plugin install 1password@1password
   
4. To confirm the plugin installed correctly, enter /plugin list and look for 1Password.

Installing the plugin registers the validation hook, the 1password-environments agent skill, and the MCP server configuration at the same time.

​

Step 3: Turn on the MCP server in 1Password

The plugin’s MCP configuration connects Claude Code to the 1Password MCP server. To turn the server on:

1. Open the 1Password desktop app.
2. Select your account or collection at the top of the sidebar, then navigate to Settings > Labs.
3. Turn on the Enable local MCP server option.
4. Go to Settings > Developer and select Integrate with MCP clients.

To confirm Claude Code connected to the server, restart Claude Code, then enter /mcp to open the MCP panel and check the status of the 1Password server.

​

Step 4: Use Claude Code to manage your Environments

Now that you have the plugin installed, you can ask Claude Code to manage your Environments on your behalf. When you first prompt Claude Code to access an Environment, you’ll get a secure authorization prompt from the 1Password desktop app that allows you to choose whether Claude Code has permission to list and create Environments.

​

Have Claude Code import an Environment and make it available in your project

If you have a plaintext .env file in your codebase, you can ask Claude Code to import its variables into a 1Password Environment. Claude Code will create the Environment then mount it at the same file path as the original file, so your project secrets are available without being tracked by Git or stored in plaintext on your device. The 1password-environments agent skill directs Claude Code to take the following steps when you prompt it to import an existing .env file into 1Password:

1. Read the .env file to get its variable names and values, then pass the values to 1Password without printing them in chat.
2. Create the Environment, or resolve the one you named. If an Environment with the name already exists, Claude Code stops and asks how you want to proceed instead of creating a duplicate. You can choose to merge the new variables into the existing Environment or create a new Environment with a different name.
3. Add the variables, with API keys, tokens, passwords, private keys, and connection strings set to concealed in 1Password.
4. Mount the Environment at the original .env file’s path, then verify the resulting local .env file.

When Claude Code needs to access the Environment, you’ll get a secure authorization prompt that allows you to choose its permissions.

​

Validate your local .env file setup

When Claude Code tries to run a command, the 1Password hook makes sure any locally mounted .env files from 1Password Environments are properly set up before the agent executes. If any required .env files are missing or invalid, the hook prevents the agent from running and the agent provides instructions for how to fix the issue. By default, the hook checks the 1Password desktop app to find locally mounted .env files related to your project based on the file path destinations configured in your Environments. To validate only specific files instead, create a .1password/environments.toml file at the root of your project with a mount_paths array.

​

Manage your Environments from Claude Code

The 1Password MCP server lets you use Claude Code to manage your 1Password Environments with secure authorization prompts. The MCP server only sees variable names, and never returns secret values stored in 1Password to the agent. Your secrets stay safe in 1Password and are only accessed by authorized processes. You can prompt Claude Code to perform tasks like:

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

The 1Password desktop app may prompt for approval when Claude Code connects to the MCP server or accesses an Environment.

​

Telemetry

The validation hook emits opt-in telemetry so 1Password can understand plugin adoption and how often common failure modes happen, like a missing file or a disabled mount. Events are only recorded if you’ve turned on product telemetry in the 1Password desktop app. They include the hook name and version, the client, the validation mode, the number of mounts checked, and whether the hook allowed or blocked the command. They don’t include file paths, file contents, Environment names, or workspace paths. Telemetry runs after the hook returns its decision to Claude Code, so it can never change whether a command is allowed. To turn telemetry off:

1. Open the 1Password desktop app.
2. Select your account or collection at the top of the sidebar, then select Manage Accounts.
3. Select Usage data then deselect Share information about your usage.

​

Learn more

• 1Password Environments
• Access secrets from 1Password through local .env files
• 1Password local .env file validation hook
• 1Password MCP server