# op-mcp
An MCP (Model Context Protocol) server that provides Claude Code with full access to the 1Password CLI (`op`). This enables Claude to securely manage passwords, secrets, vaults, users, groups, and more through natural language.
## Architecture
```
┌─────────────────────────────────────────────────────────────────────┐
│ Claude Code / LLM │
└─────────────────────────────────────────────────────────────────────┘
│
│ MCP Protocol (JSON-RPC over stdio)
▼
┌─────────────────────────────────────────────────────────────────────┐
│ op-mcp Server │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Items │ │ Vaults │ │ Users │ ... 46 tools │
│ │ (9 tools) │ │ (11 tools) │ │ (8 tools) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
│
│ CLI subprocess execution
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 1Password CLI (op) │
└─────────────────────────────────────────────────────────────────────┘
│
│ Authenticated API calls
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 1Password Service / Vaults │
└─────────────────────────────────────────────────────────────────────┘
```
## Prerequisites
1. **1Password CLI (`op`)** - Install from [1password.com/downloads/command-line](https://1password.com/downloads/command-line/)
```bash
brew install 1password-cli
op --version
```
2. **1Password App Integration** - Enable CLI integration in the 1Password desktop app:
- Open 1Password → Settings → Developer
- Enable "Integrate with 1Password CLI"
- This allows biometric unlock for CLI operations
3. **Rust toolchain** (for building from source)
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
## Installation
### From crates.io
```bash
cargo install op-mcp
```
### Build from Source
```bash
# Clone the repository
git clone https://github.com/goodwokdev/op-mcp.git
cd op-mcp
# Build release binary
cargo build --release
# The binary is at ./target/release/op-mcp
```
### Verify the Build
```bash
# Check that it responds to MCP protocol
## Claude Code Configuration
### Global Configuration (Recommended)
Use the Claude CLI to add the server globally (available in all projects):
```bash
# If installed via cargo install
claude mcp add --transport stdio 1password --scope user -- op-mcp
# If using a specific path
claude mcp add --transport stdio 1password --scope user -- ~/.mcp/bin/op-mcp
```
### Project-level Configuration
Create `.mcp.json` in your project root:
```json
{
"mcpServers": {
"1password": {
"command": "op-mcp"
}
}
}
```
### Verify Connection
After configuration, restart Claude Code or run `/mcp` to verify the server is connected.
## Usage Examples
Once configured, you can ask Claude to perform 1Password operations naturally:
### Reading Secrets
```
"What's my GitHub token from the Development vault?"
"Read the database password from op://Production/PostgreSQL/password"
"List all items in my Personal vault"
```
### Managing Items
```
"Create a new login item for api.example.com with username 'admin'"
"Update the password for my AWS root account"
"Move the 'Staging DB' item from Development to Production vault"
"Share the WiFi password item with a link that expires in 7 days"
```
### Vault Management
```
"List all vaults I have access to"
"Create a new vault called 'Client Projects'"
"Who has access to the Production vault?"
"Grant read-only access to the Shared vault for the Engineering group"
```
### User & Group Management
```
"List all users in my organization"
"Create a new group called 'DevOps Team'"
"Add user@example.com to the DevOps Team group"
"Suspend the user john.doe@example.com"
```
### Documents
```
"List all documents in the Legal vault"
"Download the SSL certificate from the Certificates vault"
"Upload this license file to the Software vault"
```
### Secret Injection
```
"Inject secrets into this .env template"
"Run this deployment script with secrets from the Production vault"
```
## Available Tools (66 total)
### Authentication (3)
| `whoami` | Get current authenticated user info |
| `signin` | Sign in to 1Password |
| `signout` | Sign out of 1Password |
### Account Management (4)
| `account_list` | List configured accounts |
| `account_get` | Get account details |
| `account_add` | Add a new account |
| `account_forget` | Remove account from device |
### Vault Management (11)
| `vault_list` | List accessible vaults |
| `vault_get` | Get vault details |
| `vault_create` | Create a new vault |
| `vault_edit` | Edit vault properties |
| `vault_delete` | Delete a vault |
| `vault_user_list` | List users with vault access |
| `vault_user_grant` | Grant user access to vault |
| `vault_user_revoke` | Revoke user's vault access |
| `vault_group_list` | List groups with vault access |
| `vault_group_grant` | Grant group access to vault |
| `vault_group_revoke` | Revoke group's vault access |
### Item Management (9)
| `item_list` | List items (with filters) |
| `item_get` | Get item details |
| `item_create` | Create a new item |
| `item_edit` | Edit item fields |
| `item_delete` | Delete or archive an item |
| `item_move` | Move item between vaults |
| `item_share` | Create a share link |
| `item_template_list` | List available templates |
| `item_template_get` | Get template details |
### Document Management (5)
| `document_list` | List documents |
| `document_get` | Download document content |
| `document_create` | Upload a new document |
| `document_edit` | Replace document content |
| `document_delete` | Delete a document |
### User Management (8)
| `user_list` | List users in account |
| `user_get` | Get user details |
| `user_provision` | Create a new user |
| `user_confirm` | Confirm pending user |
| `user_edit` | Edit user properties |
| `user_suspend` | Suspend a user |
| `user_reactivate` | Reactivate suspended user |
| `user_delete` | Remove user from account |
### Group Management (8)
| `group_list` | List groups |
| `group_get` | Get group details |
| `group_create` | Create a new group |
| `group_edit` | Edit group properties |
| `group_delete` | Delete a group |
| `group_user_list` | List group members |
| `group_user_grant` | Add user to group |
| `group_user_revoke` | Remove user from group |
### Connect Server Management (11)
| `connect_server_list` | List Connect servers |
| `connect_server_get` | Get server details |
| `connect_server_create` | Create a Connect server |
| `connect_server_edit` | Edit server properties |
| `connect_server_delete` | Delete a Connect server |
| `connect_token_list` | List server tokens |
| `connect_token_create` | Create a new token |
| `connect_token_edit` | Edit token properties |
| `connect_token_delete` | Revoke a token |
| `connect_vault_grant` | Grant server vault access |
| `connect_vault_revoke` | Revoke server vault access |
### Service Account (2)
| `service_account_create` | Create a service account |
| `service_account_ratelimit` | Check rate limit status |
### Events API (1)
| `events_api_create` | Set up Events API integration |
### Secrets (3)
| `secret_read` | Read a secret by reference |
| `secret_inject` | Inject secrets into template |
| `secret_run` | Run command with secrets as env vars |
## Security Considerations
- **Biometric Authentication**: When integrated with the 1Password app, operations require biometric confirmation
- **No Secret Storage**: This server doesn't store any secrets; it proxies requests to the `op` CLI
- **Audit Trail**: All operations are logged by 1Password
- **Permission Scoping**: Access is limited to what your 1Password account can access
## Troubleshooting
### "1Password CLI (op) not found"
Ensure `op` is installed and in your PATH:
```bash
which op
op --version
```
### "Not signed in to 1Password"
Sign in using the 1Password app or CLI:
```bash
op signin
```
### "Permission denied"
- Check that CLI integration is enabled in 1Password app settings
- Verify you have access to the requested vault/item
- For team accounts, ensure your role has the required permissions
### Server not appearing in Claude Code
1. Check the path in your configuration is absolute and correct
2. Verify the binary is executable: `chmod +x /path/to/op-mcp`
3. Restart Claude Code after configuration changes
4. Run `/mcp` in Claude Code to see server status
## Development
```bash
# Run in debug mode
cargo run
# Run tests
cargo test
# Check formatting
cargo fmt --check
# Run linter
cargo clippy
```
## License
MIT