# 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](https://bun.sh/) runtime
- [1Password CLI](https://1password.com/downloads/command-line/) (`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)

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

### Option 2: Password-based Auto-signin

```bash
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)

```bash
export OP_ACCOUNT="my"  # Your account shorthand
```

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

## Installation

```bash
cd op-mcp.bun
bun install
```

## Usage

### Running the server

```bash
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`)

```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

```bash
# 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

```bash
# 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