> ## Documentation Index
> Fetch the complete documentation index at: https://www.1password.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Use Claude Code with 1Password Environments
> Give Claude Code the 1Password Environments workflow, validate locally mounted .env files, and connect to the 1Password MCP server.
export const BetaBadge = ({content}) => {
if (content) {
return
Beta
;
}
return <>
Beta
;
};
The [1Password plugin for Claude Code ](https://github.com/1Password/1password-claude-plugin) connects [1Password Environments](/environments) to [Claude Code ](https://code.claude.com/docs/en/overview). The plugin includes:
* An MCP configuration for the [1Password MCP server](/environments/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](/environments/local-env-file) are set up correctly.
## Requirements
* [1Password subscription](https://1password.com/pricing/password-manager)
* 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux)
* [Claude Code ](https://code.claude.com/docs/en/overview)
* [`sqlite3` ](https://sqlite.org/index.html) installed and available in your PATH, for the validation hook. It's pre-installed on Mac, and available through your package manager on Linux.
**Platform support**
The [1Password MCP server](/environments/mcp-server) and [locally mounted `.env` files](/environments/local-env-file) are currently only supported on Mac and Linux. On Windows, the validation hook exits without a decision, so it never blocks Claude Code from running commands.
## Step 1: Set up your Environments
Before you get started, you can set up the [Environments](/environments/) that Claude Code will interact with.
1. [Create one or more Environments](/environments) in 1Password to store your project secrets.
2. [Configure locally mounted `.env` files](/environments/local-env-file) for them.
You can also wait and [use the plugin to import your existing `.env` file](#have-claude-code-import-an-environment-and-make-it-available-in-your-project) and mount a local `.env` file destination on your behalf.
## Step 2: Install the plugin
The 1Password plugin is distributed from its [GitHub repository ](https://github.com/1Password/1password-claude-plugin). 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:
```shell theme={null}
/plugin marketplace add 1Password/1password-claude-plugin
```
3. Install the plugin:
```shell theme={null}
/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
1Password Enterprise Password Manager admins can turn the MCP server feature on and off. To do so, [sign in](https://start.1password.com/signin/) to your account on 1Password.com, then go to **Policies** > **Agentic permissions** and turn the **Local MCP server** option on or off as needed.
The plugin's MCP configuration connects Claude Code to the [1Password MCP server](/environments/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.
After Claude Code imports your `.env` file, make sure to rotate all secrets that were previously stored in plaintext. Moving your project secrets to 1Password protects them going forward, but doesn't mitigate any past exposure, such as in your Git history or your coding agent memory.
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](/environments/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.
The contents of locally mounted `.env` files aren't tracked by Git or stored on your device, and are only available at the moment you access them.
### 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](/environments/agent-hook-validate#step-3-choose-how-you-want-the-hook-to-validate-your-env-files).
See how the hook discovers your mounted files, the validation modes you can configure, and how to use it with other agents and IDEs.
### Manage your Environments from Claude Code
The [1Password MCP server](/environments/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`"
Make sure to rotate any secrets you import to 1Password that were previously stored in plaintext in your codebase or `.env` files. Moving your project secrets to 1Password secures them going forward, but doesn't mitigate any past exposure, such as in your Git history or your coding agent memory.
The 1Password desktop app may prompt for approval when Claude Code connects to the MCP server or accesses an Environment.
See how the MCP server handles authorization, why your secrets stay out of the agent's context, and how to use it with other MCP clients.
## 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](/environments)
* [Access secrets from 1Password through local `.env` files](/environments/local-env-file)
* [1Password local `.env` file validation hook](/environments/agent-hook-validate)
* [1Password MCP server](/environments/mcp-server)
## Related topics
- [Use Claude Code with 1Password Environments](/integrations/claude-plugin.md)
- [Use the 1Password MCP Server to manage your 1Password Environments](/environments/mcp-server.md)
- [Use 1Password to authenticate Claude Code with biometrics](/cli/shell-plugins/claude-code.md)