op-mcp

op-mcp

MCP (Model Context Protocol) server for 1Password CLI, implemented in Bun TypeScript.

This is a port of the Rust op-mcp implementation to TypeScript for use with Bun runtime.

Features

• Wraps the 1Password CLI (op) as an MCP server
• Exposes 65 tools for managing 1Password resources
• Full TypeScript type safety with Zod schema validation
• Supports all major 1Password operations:
• Authentication (whoami, signin, signout)
• Account management
• Vault operations
• Item CRUD
• Document management
• User management
• Group management
• Connect server management
• Service accounts
• Events API
• Secret reading and injection

Prerequisites

• Bun runtime
• 1Password CLI (op) installed and in PATH
• 1Password account with CLI access configured

Authentication

The server supports automatic authentication via environment variables:

Option 1: Service Account Token (Recommended for automation)

export OP_SERVICE_ACCOUNT_TOKEN="your-service-account-token"

Option 2: Password-based Auto-signin

export OP_ACCOUNT="my"  # Your account shorthand
export OP_PASSWORD="your-password"

When both OP_ACCOUNT and OP_PASSWORD are set, the server automatically signs in on startup.

Option 3: Default Account (Manual signin required)

export OP_ACCOUNT="my"  # Your account shorthand

This sets the default account but requires you to be already signed in via op signin.

Installation

cd op-mcp.bun
bun install

Usage

Running the server

bun run start
# or
bun run src/index.ts

MCP Configuration

Add to your MCP client configuration file.

Claude Code (~/.claude.json)

Password-based auto-signin: ``json { "mcpServers": { "1password": { "command": "bun", "args": ["run", "/home/won/lab/config/op-mcp/op-mcp.bun/src/index.ts"], "env": { "OP_ACCOUNT": "my", "OP_PASSWORD": "your-password" } } } } ``

Service account token: ``json { "mcpServers": { "1password": { "command": "bun", "args": ["run", "/home/won/lab/config/op-mcp/op-mcp.bun/src/index.ts"], "env": { "OP_SERVICE_ACCOUNT_TOKEN": "ops_..." } } } } ``

Default account (requires manual signin): ``json { "mcpServers": { "1password": { "command": "bun", "args": ["run", "/home/won/lab/config/op-mcp/op-mcp.bun/src/index.ts"], "env": { "OP_ACCOUNT": "my" } } } } ``

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)

{
  "mcpServers": {
    "1password": {
      "command": "/path/to/bun",
      "args": ["run", "/path/to/op-mcp.bun/src/index.ts"],
      "env": {
        "OP_ACCOUNT": "my",
        "OP_PASSWORD": "your-password"
      }
    }
  }
}

Environment Variables Reference

| Variable | Description | |----------|-------------| | OP_SERVICE_ACCOUNT_TOKEN | Service account token for authentication (takes priority) | | OP_ACCOUNT | Account shorthand (e.g., my, work) | | OP_PASSWORD | Password for auto-signin (requires OP_ACCOUNT) |

Tools

The server exposes 65 tools organized by domain:

Authentication (3 tools)

• whoami - Get current user info
• signin - Sign in to 1Password
• signout - Sign out of 1Password

Account (4 tools)

• account_list - List configured accounts
• account_get - Get account details
• account_add - Add a new account
• account_forget - Remove an account from device

Vault (11 tools)

• vault_list - List vaults
• vault_get - Get vault details
• vault_create - Create a vault
• vault_edit - Edit a vault
• 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 access from vault
• vault_group_list - List groups with vault access
• vault_group_grant - Grant group access to vault
• vault_group_revoke - Revoke group access from vault

Item (9 tools)

• item_list - List items
• item_get - Get item details
• item_create - Create an item
• item_edit - Edit an item
• item_delete - Delete an item
• item_move - Move item to another vault
• item_share - Create shareable link
• item_template_list - List item templates
• item_template_get - Get template details

Document (5 tools)

• document_list - List documents
• document_get - Download document
• document_create - Upload document
• document_edit - Replace document content
• document_delete - Delete document

User (8 tools)

• user_list - List users
• user_get - Get user details
• user_provision - Create new user
• user_confirm - Confirm pending user
• user_edit - Edit user
• user_suspend - Suspend user
• user_reactivate - Reactivate user
• user_delete - Delete user

Group (8 tools)

• group_list - List groups
• group_get - Get group details
• group_create - Create group
• group_edit - Edit group
• group_delete - Delete group
• group_user_list - List group members
• group_user_grant - Add user to group
• group_user_revoke - Remove user from group

Connect (11 tools)

• connect_server_list - List Connect servers
• connect_server_get - Get server details
• connect_server_create - Create server
• connect_server_edit - Edit server
• connect_server_delete - Delete server
• connect_token_list - List tokens
• connect_token_create - Create token
• connect_token_edit - Edit token
• connect_token_delete - Delete token
• connect_vault_grant - Grant vault access
• connect_vault_revoke - Revoke vault access

Service Account (2 tools)

• service_account_create - Create service account
• service_account_ratelimit - Check rate limit

Events API (1 tool)

• events_api_create - Create Events API integration

Secrets (3 tools)

• secret_read - Read secret by reference
• secret_inject - Inject secrets into template
• secret_run - Run command with secrets

Development

# Type check
bun run typecheck

# Build (optional)
bun run build

Testing

The project includes a comprehensive integration test suite that runs against a real 1Password account.

Prerequisites

Ensure you're authenticated before running tests: ``bash export OP_ACCOUNT="my" export OP_PASSWORD="your-password" ``

Running Tests

# Run all tests
bun test

# Run specific test suites
bun test:auth      # Authentication tests
bun test:account   # Account management tests
bun test:vault     # Vault CRUD tests
bun test:item      # Item CRUD tests
bun test:document  # Document upload/download tests
bun test:user      # User management tests (admin required)
bun test:group     # Group management tests
bun test:connect   # Connect server tests (Business/Teams required)
bun test:service   # Service account tests
bun test:events    # Events API tests (Business/Enterprise required)
bun test:secrets   # Secret read/inject tests

Test Behavior

• Tests create resources with op-mcp-test prefix for easy identification
• Resources are cleaned up after each test suite
• Tests that require admin privileges or specific account types are automatically skipped
• A test vault named op-mcp-test-vault is created/reused for item and document tests

License

MIT