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

• Features

• Requirements

• Project structure

• Quick start (Docker)

  • 1. Build the image

  • 2. Authenticate

  • 3. Configure your MCP client

• Running without Docker

• Available tools

• Environment variables

• Security considerations

• Troubleshooting

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

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

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

Environment variables

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.