Skip to main content
Glama
protonpass-mcp

protonpass-mcp

by aureTheDev

protonpass-mcp

A Model Context Protocol (MCP) server for Proton Pass. It wraps the official pass-cli binary and exposes 14 tools so any MCP-compatible AI assistant (Claude Desktop, Claude Code, etc.) can manage your vaults, credentials, and secrets.

Note: Proton Pass has no public REST API. This server uses the official pass-cli binary under the hood. The CLI is currently in beta and requires a Visionary or higher Proton plan.


Table of contents


Related MCP server: Proton-MCP

Features

  • Vault management — list, create, share vaults

  • Item management — list, view, create (login / note), update, trash, restore

  • TOTP — read live 2FA codes from stored items

  • Secret references — retrieve any field via pass://Vault/Item/field URIs

  • Password generation — generate cryptographically secure passwords

  • Account info — inspect the currently authenticated Proton account

  • Dockerized — no local Node.js or pass-cli installation required on the host

  • Persistent sessions — session tokens survive container restarts via a named Docker volume


Requirements

Dependency

Version

Docker

24+

Proton Pass account

Visionary plan or higher (CLI beta requirement)

No Node.js, npm, or pass-cli installation is needed on your host machine — everything runs inside the Docker image.


Project structure

protonpass-mcp/
├── src/
│   └── index.ts          # MCP server — tool definitions and handlers
├── Dockerfile            # Multi-stage build (TypeScript → runtime + pass-cli)
├── docker-compose.yml    # Optional: run via Compose
├── mcp-config.json       # MCP client configuration snippet
├── .env.example          # Environment variable template
├── package.json
└── tsconfig.json

Quick start (Docker)

1. Build the image

docker build -t protonpass-mcp .

The build installs Node.js, downloads and installs pass-cli from Proton's official installer, compiles the TypeScript source, and produces a minimal runtime image.

2. Authenticate

The MCP server is non-interactive. Run this once to log in and save the session to the named Docker volume:

docker run --rm -it \
  -e PROTON_PASS_KEY_PROVIDER=fs \
  -v protonpass-session:/root/.local/share/proton-pass-cli \
  --entrypoint pass-cli \
  protonpass-mcp:latest login --interactive

Enter your Proton credentials (email, password, TOTP if enabled) when prompted. The session token and encryption key are written to the protonpass-session volume and reused automatically on every subsequent server start.

To verify the session is working:

docker run --rm \
  -e PROTON_PASS_KEY_PROVIDER=fs \
  -v protonpass-session:/root/.local/share/proton-pass-cli \
  --entrypoint pass-cli \
  protonpass-mcp:latest user info

Windows (cmd / PowerShell): Replace \ line continuations with ^ (cmd) or ` (PowerShell), or write the command on a single line.

Tip: Re-run the login command if your session expires.

3. Configure your MCP client

Copy the contents of mcp-config.json into your client's configuration file.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "protonpass": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "PROTON_PASS_KEY_PROVIDER=fs",
        "-e", "PASS_LOG_LEVEL=warn",
        "-v", "protonpass-session:/root/.local/share/proton-pass-cli",
        "protonpass-mcp:latest"
      ]
    }
  }
}

Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "protonpass": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "PROTON_PASS_KEY_PROVIDER=fs",
        "-e", "PASS_LOG_LEVEL=warn",
        "-v", "protonpass-session:/root/.local/share/proton-pass-cli",
        "protonpass-mcp:latest"
      ]
    }
  }
}

After saving the config, restart your MCP client. The server starts automatically on demand — Docker launches a fresh container for every session and removes it when done (--rm).


Running without Docker

If pass-cli and Node.js (v22+) are already installed on your machine:

npm install
npm run build
node dist/index.js

Configure your MCP client to run node /path/to/protonpass-mcp/dist/index.js directly.


Available tools

Tool

Description

Required params

list_vaults

List all accessible vaults

—

create_vault

Create a new vault

name

list_items

List items (all vaults or filtered)

—

view_item

View full item details including credentials

item_id, vault_id

create_login

Create a login credential item

vault_id, title

create_note

Create a secure note item

vault_id, title, note

update_item

Update fields of an existing item

item_id, vault_id

trash_item

Move an item to trash (soft delete)

item_id, vault_id

restore_item

Restore a trashed item

item_id, vault_id

get_totp

Get the current live TOTP code

item_id, vault_id

generate_password

Generate a secure random password

—

view_secret

Read a field via pass:// URI

uri

get_user_info

Show authenticated account details

—

share_vault

Share a vault with another Proton user

vault_id, email, role

Secret URI format

The view_secret tool accepts pass:// URIs identifying any field of any item:

pass://<vault-name>/<item-name>/<field>

Built-in fields: username, password, email, url, note, totp. Custom fields are addressed by their exact name (case-sensitive).

Examples:

pass://Work/GitHub/password
pass://Personal/Netflix/username
pass://Servers/Production DB/note

Vault sharing roles

Role

Permissions

manager

Read, write, share

editor

Read, write

viewer

Read-only


Environment variables

Variable

Default

Description

PROTON_PASS_KEY_PROVIDER

keyring

Key storage backend. Use fs in Docker (no system keyring).

PROTON_PASS_ENCRYPTION_KEY

—

Encryption key when KEY_PROVIDER=env. SHA-256 hashed internally.

PROTON_PASS_SESSION_DIR

platform default

Override session storage path.

PASS_LOG_LEVEL

info

Log verbosity: trace, debug, info, warn, error, off.

When using Docker Compose, copy .env.example to .env and edit the values — Compose picks it up automatically:

cp .env.example .env

Otherwise, set them in docker-compose.yml or in the args array of your MCP client config.


Security considerations

  • Session volume: The protonpass-session Docker volume contains your Proton Pass session token and (when using PROTON_PASS_KEY_PROVIDER=fs) your encryption key. Treat it with the same care as a private key file. Back it up securely.

  • PROTON_PASS_ENCRYPTION_KEY: If you set this variable, do not store it in version-controlled files. Pass it via a secrets manager or a .env file excluded from git.

  • Command injection: The server uses execFile with argument arrays — no shell interpolation occurs. User-supplied strings are passed as discrete arguments, not interpolated into a shell command.

  • No secrets in tool output: view_item and view_secret return whatever pass-cli outputs. Ensure your MCP client does not log tool results to untrusted locations.

  • Container isolation: Each MCP session spawns an isolated container (--rm). The container has no network access beyond what Docker grants by default and no host filesystem access beyond the named session volume.


Troubleshooting

Error: pass-cli: command not found The image was not built with the Proton installer. Rebuild with docker build --no-cache -t protonpass-mcp ..

Error: no session found / Error: not authenticated Re-run the authentication command from step 2. The session may have expired.

Error: permission denied on volume Ensure the protonpass-session volume was created by Docker and is accessible. Run docker volume inspect protonpass-session to verify.

pass-cli hangs on login inside the container The --interactive flag is required for terminal-based login. Make sure it is present in the docker run command.

Items return IDs but you need names Use list_vaults to get vault share IDs, then list_items with that vault_id to get item IDs. The view_secret tool accepts human-readable names via the pass:// URI syntax.

Available Tools

14 tools
create_loginB

Create a new login credential item in a vault.

Inputs: title (required), vault_id (required), url, note, +2 more.

create_noteA

Create a new secure note item in a vault.

Inputs: note (required), title (required), vault_id (required).

create_vaultB

Create a new Proton Pass vault.

Inputs: name (required).

generate_passwordB

Generate a cryptographically secure random password.

Inputs: length.

get_totpA

Get the current TOTP one-time code for an item that has 2FA configured.

Inputs: item_id (required), vault_id (required).

get_user_infoA

Get information about the currently authenticated Proton account.

Inputs: no named parameters.

list_itemsA

List items stored in a vault. Omit vault_id to list items across all vaults.

Inputs: vault_id.

list_vaultsA

List all Proton Pass vaults accessible to the current account.

Inputs: no named parameters.

restore_itemB

Restore a trashed item.

Inputs: item_id (required), vault_id (required).

share_vaultB

Share a vault with another Proton user by email.

Inputs: role (required), email (required), vault_id (required).

trash_itemA

Move an item to trash (soft delete). Use restore_item to undo.

Inputs: item_id (required), vault_id (required).

update_itemA

Update an existing item. Only the fields you supply will change.

Inputs: item_id (required), vault_id (required), url, note, +3 more.

view_itemB

View the full details of an item (title, username, password, URLs, notes, custom fields, etc.).

Inputs: item_id (required), vault_id (required).

view_secretA

Retrieve a specific field value from an item using a pass:// URI. URI format: pass://// Fields: username, password, email, url, note, totp, or custom field name. Example: pass://Work/GitHub/password

Inputs: uri (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 14 tools

    Disambiguation4/5

    Each tool targets a specific resource and action, with only minor overlap between get_totp and view_secret (which can retrieve the totp field via URI). For example, list_items vs view_item are clearly distinct in scope (metadata vs full details).

    Naming Consistency5/5

    All tools follow a consistent verb_noun snake_case pattern (e.g., list_vaults, create_note, trash_item, generate_password). There is no mixing of camelCase, vague verbs, or irregular naming conventions.

    Tool Count5/5

    14 tools is well-scoped for a password manager, covering vaults, items, lifecycle, sharing, TOTP, and password generation. Each tool has a distinct place and the set feels intentional rather than bloated.

    Completeness4/5

    The tool surface covers core CRUD/lifecycle for vaults and items, plus sharing, TOTP retrieval, and password generation. Minor gaps exist, such as no permanent delete (only trash/restore) and limited item creation types (only login and note), but these are workable.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      MCP server for Vaultwarden/Bitwarden vault management. Enables AI agents to securely create, search, read, and update vault items via the official Bitwarden CLI, with safe-by-default redaction and support for both stdio and SSE transports.
      53
      29
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server for pCloud cloud storage. Enables AI assistants like Claude to interact with your pCloud - listing files, creating folders, searching, sharing, and more.
      15
      2
      GPL 3.0