protonpass-mcp
Provides tools for managing Proton Pass vaults, items (logins/notes), TOTP codes, secret references, password generation, and vault sharing via the official pass-cli binary.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@protonpass-mcp show me my login for github.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-clibinary 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/fieldURIsPassword generation — generate cryptographically secure passwords
Account info — inspect the currently authenticated Proton account
Dockerized — no local Node.js or
pass-cliinstallation required on the hostPersistent 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.jsonQuick 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 --interactiveEnter 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 infoWindows (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.jsConfigure your MCP client to run node /path/to/protonpass-mcp/dist/index.js directly.
Available tools
Tool | Description | Required params |
| List all accessible vaults | — |
| Create a new vault |
|
| List items (all vaults or filtered) | — |
| View full item details including credentials |
|
| Create a login credential item |
|
| Create a secure note item |
|
| Update fields of an existing item |
|
| Move an item to trash (soft delete) |
|
| Restore a trashed item |
|
| Get the current live TOTP code |
|
| Generate a secure random password | — |
| Read a field via |
|
| Show authenticated account details | — |
| Share a vault with another Proton user |
|
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/noteVault sharing roles
Role | Permissions |
| Read, write, share |
| Read, write |
| Read-only |
Environment variables
Variable | Default | Description |
|
| Key storage backend. Use |
| — | Encryption key when |
| platform default | Override session storage path. |
|
| Log verbosity: |
When using Docker Compose, copy .env.example to .env and edit the values — Compose picks it up automatically:
cp .env.example .envOtherwise, set them in docker-compose.yml or in the args array of your MCP client config.
Security considerations
Session volume: The
protonpass-sessionDocker volume contains your Proton Pass session token and (when usingPROTON_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.envfile excluded from git.Command injection: The server uses
execFilewith 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_itemandview_secretreturn whateverpass-clioutputs. 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 toolscreate_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).
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
Scored across 14 tools
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).
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.
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.
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
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Zotero MCP server for Claude and ChatGPT: search, citations, safe writes, PDF passages and pages.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP 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.5329MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for the Proton privacy suite — Mail, Pass, Drive, Calendar, and VPN. 36 tools for Claude and other MCP-compatible AI agents.30MIT
- AlicenseAqualityDmaintenanceA 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.152GPL 3.0
- AlicenseAqualityDmaintenanceA Model Context Protocol (MCP) server that provides a bridge to Anthropic's Claude CLI. It allows MCP-compliant clients like Claude Desktop or Gemini to start new chat sessions or continue existing ones.2108 npmISC