Skip to main content
Glama
proton-pass-community-mcp

proton-pass-community-mcp

by hesreallyhim

CI Production Hygiene NPM Version Codacy Badge Dependabot Updates OpenSSF Scorecard OpenSSF Best Practices

proton-pass-community-mcp is an MCP server for Proton Pass, with broad coverage of pass-cli operations.

It is an independent community project. It is not affiliated with or endorsed by Proton AG.

The integration provides:

  • typed tool inputs with zod

  • stdio transport for MCP clients

CLI compatibility baseline: 2.3.3

The current rehabilitation targets the existing 47 tools against the published CLI 2.3.3 source. Validation covers schemas, subprocess behavior, fixtures, and the installed npm package; live vault compatibility has not been revalidated. See the compatibility audit for per-tool evidence and limits.

Available Tools

The server exposes the following MCP tool surface:

Tool

Purpose

view_session_info

Session/account status from pass-cli info

view_user_info

User account details from pass-cli user info

check_status

Check user authentication status and CLI version

inject

Inject secrets into template files

run

Run commands with secret references resolved

list_vaults

List vaults

list_shares

List shares

list_invites

List pending invitations

accept_invite

Accept an invitation token

reject_invite

Reject an invitation token

view_settings

View current Proton Pass CLI settings

list_vault_members

List members of a specific vault

update_vault_member

Update a vault member role

remove_vault_member

Remove a vault member

list_items

List vault or share items, omitting contents

search_items

Search items by title

view_item

View item by URI or selectors

create_vault

Create a vault

update_vault

Update a vault name

delete_vault

Delete a vault

share_vault

Share a vault with a user

transfer_vault

Transfer vault ownership

create_login_item

Create a login item

create_login_item_from_template

Create a login item from template payload

create_note_item

Create a note item

create_credit_card_item

Create a credit card item

create_wifi_item

Create a WiFi item

create_custom_item

Create a custom item from template payload

create_identity_item

Create an identity item from template payload

move_item

Move an item between vaults

trash_item

Move an item to trash

untrash_item

Restore an item from trash

update_item

Update an item field set

delete_item

Delete an item

download_item_attachment

Download an item attachment

list_item_members

List members of an item

update_item_member

Update an item member role

remove_item_member

Remove an item member

create_item_alias

Create an alias item

share_item

Share an item with a user

generate_item_totp

Generate item TOTP codes

generate_random_password

Generate a random password

generate_passphrase

Generate a passphrase

generate_totp

Generate TOTP from secret/URI

score_password

Score password strength

Coverage goal: provide comprehensive support for Proton Pass CLI workflows that fit MCP tool semantics. Intentionally excluded are CLI behaviors that are purely interactive or otherwise not a good fit for reliable MCP tool execution.

The search_items operation is additional functionality that is not provided by the base CLI.

Mutative tools require write gate opt-in (ALLOW_WRITE=1) and explicit per-call confirmation (confirm: true). This includes download_item_attachment, which can overwrite a local file, and inject/run. delete_item permanently deletes an item without requiring it to be trashed first.

Changed input requirements: update_item, trash_item, untrash_item, and update_vault require an explicit agentReason for every session type. CLI 2.3.3 can apply these mutations before validating an agent audit reason, so the server validates the reason before invoking the CLI. Other audited tools accept an optional agentReason; see audit-reason policy.

Proposed protocol-aligned confirmation policy (elicitation-first with fail-closed fallback) is documented in docs/TOOL_SCHEMA_PLAN.md.

Related MCP server: protonpass-mcp

Available Resources

The server also exposes static MCP resources for item-create template snapshots:

  • pass://templates/item-create (catalog/index)

  • pass://templates/item-create/login

  • pass://templates/item-create/note

  • pass://templates/item-create/credit-card

  • pass://templates/item-create/wifi

  • pass://templates/item-create/custom

  • pass://templates/item-create/identity

Snapshot artifact source:

These resources reflect the six existing CLI template types, refreshed from the 2.3.3 source without executing the CLI. They are examples, not authoritative validation schemas or necessarily create-ready values (WiFi still needs a nonblank SSID). Login templates now include totp_uri.

Item Discovery Contract

list_items and search_items project CLI JSON into item references, omitting nested item contents and secrets. Unknown JSON envelopes and invalid JSON fail without returning the raw payload. The legacy list_items.output: "human" hint also returns JSON references and cannot bypass this projection; it does not accept pagination parameters. Explicit view_item field reads preserve the field's text rather than parsing JSON-looking secrets.

list_items and search_items both support MCP pagination:

  • Input fields:

    • pageSize (optional, 1..250, default 100 for JSON output)

    • cursor (optional non-negative integer string offset, for example "100")

  • Behavior:

    • Response includes items, pageSize, cursor, returned, total, and nextCursor.

    • Use nextCursor in a follow-up call to fetch the next page.

list_items also forwards filterType, filterState, and sortBy to pass-cli item list.

search_items semantics:

  • title-only search (field: "title")

  • matching modes: contains, prefix, exact

  • optional caseSensitive

  • an omitted vault/share selector searches the CLI's default vault, not all vaults

Requirements

NOTE

Currently, the server expects the user to handle authentication. If it's not able to authenticate, it will simply prompt the user to authenticate using one of thepass-cli methods.

  • Node.js 24 (.nvmrc)

  • pass-cli installed and authenticated

  • MCP client capable of stdio transport

  • For project development and testing, use the repo wrapper (npm run pass -- <args> or scripts/pass-dev.sh <args>) instead of bare pass-cli so auth stays in the repo-local session scope.

Run Locally

npm ci
npm run build
npm run dev

For project-side pass-cli work, prefer:

npm run pass -- info

This routes through the repo wrapper, which uses a project-local session dir and avoids OS keychain/keyring by default. To assert that the active repo-local session is the intended throwaway account before mutative work:

export PASS_DEV_EXPECTED_ACCOUNT=<throwaway-account-identifier>
npm run pass:dev:preflight

Install and Run via npm/npx

Install from npm or run directly with npx:

npm install --global proton-pass-community-mcp
proton-pass-community-mcp --allow-version-drift

or:

npx -y proton-pass-community-mcp --allow-version-drift

Release operations for maintainers are documented in docs/DEPLOYMENT.md.

Anonymized Demo Shell (Docker)

Use this when recording demos and you want a neutral workspace path in tooling metadata:

npm run demo:shell

This launches a container with the project mounted at /workspace/project.

To run a single command instead of an interactive shell:

npm run demo:shell -- npm run check

Notes:

  • Shell prompt aliases/PS1 tweaks only change terminal display; they do not change real working-directory metadata emitted by tools.

  • For true path anonymization in logs, run the host/tooling process from inside this containerized workspace.

MCP Client Configuration

Example MCP server config using npx package execution:

{
  "mcpServers": {
    "proton-pass-community-mcp": {
      "command": "npx",
      "args": ["-y", "proton-pass-community-mcp", "--allow-version-drift"]
    }
  }
}

If you are developing locally from source, use a direct local build path:

Example MCP server config using command-line args:

{
  "mcpServers": {
    "proton-pass-community-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/proton-pass-community-mcp/dist/index.js", "--allow-version-drift"]
    }
  }
}

Example MCP server config using environment overrides:

{
  "mcpServers": {
    "proton-pass": {
      "command": "node",
      "args": ["/absolute/path/to/proton-pass-community-mcp/dist/index.js"],
      "env": {
        "PASS_CLI_BIN": "pass-cli",
        "PASS_CLI_ALLOW_VERSION_DRIFT": "true"
      }
    }
  }
}

Authentication Model

  1. Authentication is user-managed outside MCP with pass-cli login.

  2. The pass-cli session may be established with normal account credentials or with a pre-provisioned personal access token (PAT).

  3. On auth failure, tools return standardized AUTH_* errors and a retry instruction.

  4. The MCP server does not collect credentials, OTP codes, private keys, or PAT values.

  5. PAT-backed login does not change the boundary: login/logout remain outside MCP, and PAT provisioning is not currently exposed as an MCP tool surface.

  6. For project development, the canonical pass-cli entrypoint is the repo wrapper (npm run pass -- <args> / scripts/pass-dev.sh <args>), not bare pass-cli.

  7. The repo wrapper isolates project auth into .tmp/proton-pass-dev-session and avoids default keychain/keyring access, but it does not by itself prove the correct account is active; use scripts/pass-dev-preflight.sh or npm run pass:dev:preflight to assert the expected throwaway account.

  8. Use check_status once as a session preflight (not per tool call); rely on AUTH_* fallback errors if the session later expires.

  9. check_status compares your local CLI version against the development baseline and reports a version assessment for LLMs:

    • equal: exact semver match

    • compatible: semver differs but appears compatible by policy

    • possibly_incompatible: semver indicates potential drift, or version parsing/execution prevented a strict comparison

  10. Version assessments are advisory. check_status is marked as an MCP error only when connectivity/authentication fails.

  11. There is no MCP-specific API token auth layer in this server. Authentication methods are those supported by pass-cli in the server process environment.

  12. Agent provisioning and agent-token login also remain outside MCP. agentReason is an audit explanation, not a credential or authorization grant. It is forwarded only to that invocation as PROTON_PASS_AGENT_REASON; the server does not invent reasons or mutate its process environment. Non-agent sessions can omit it except on the four mutation tools listed above. Permission/capability denials remain errors rather than instructions to reauthenticate.

  13. A valid reason does not make mutation and audit delivery atomic. Never automatically retry a failed mutation: inspect its state first. check_status uses info plus --version; it is a session preflight, not proof that every capability or remote API call will succeed.

Test Account Workflow

For disposable test-account usage in local development and CI (including account preflight checks and session isolation), see docs/testing/TEST_ACCOUNT_WORKFLOW.md.

Startup Flags

  • --allow-version-drift: treat semver mismatch/version-parse uncertainty as compatible for check_status

Equivalent environment variable:

  • PASS_CLI_ALLOW_VERSION_DRIFT=true|false (accepted truthy values: true, 1, yes, on; falsy: false, 0, no, off)

  • If both are set, the CLI flag takes precedence.

Example:

npm run dev -- --allow-version-drift

Notes

  • This is not an official Proton project.

  • This project currently targets Proton Pass via pass-cli only.

  • See ROADMAP.md for planned features.

  • In addition to the MCP server, there is an agent skill file that is intended to be integrated with this MCP - however, it is currently only a draft.

  • Developer runtime configuration and validation workflows are documented in CONTRIBUTING.md.

  • Disposable account setup and contributor/CI guidance are documented in docs/testing/TEST_ACCOUNT_WORKFLOW.md.

  • See CONTRIBUTING.md if you're interested in contributing to this project. Contributors are welcome.

LICENSE

GPL-3 &copy; 2026 Really Him

Available Tools

47 tools
accept_inviteC

Accept an invitation token.

Inputs: inviteToken (required), confirm.

check_statusA

Run preflight checks for connectivity/authentication and CLI version compatibility.

Inputs: no named parameters.

create_credit_card_itemB

Create a credit card item in a vault or share.

Inputs: title (required), cvv, pin, note, +7 more.

create_custom_itemB

Create a custom item from template payload in a vault or share.

Inputs: template (required), confirm, shareId, vaultName, +1 more.

create_identity_itemC

Create an identity item from template payload in a vault or share.

Inputs: template (required), confirm, shareId, vaultName, +1 more.

create_item_aliasB

Create an email alias item.

Inputs: prefix (required), output, confirm, shareId, +1 more.

create_login_itemC

Create a login item in a vault or share.

Inputs: title (required), url, email, confirm, +6 more.

create_login_item_from_templateB

Create a login item from template JSON.

Inputs: template (required), confirm, shareId, vaultName, +1 more.

create_note_itemB

Create a note item in a vault or share.

Inputs: title (required), note, confirm, shareId, +2 more.

create_vaultC

Create a new vault.

Inputs: name (required), confirm.

create_wifi_itemA

Create a WiFi item in a vault or share.

Inputs: ssid (required), title (required), note, confirm, +5 more.

delete_itemA

Permanently delete an item by share ID and item ID, bypassing trash.

Inputs: itemId (required), shareId (required), confirm, agentReason.

delete_vaultC

Delete a vault by share ID or vault name.

Inputs: confirm, shareId, vaultName.

download_item_attachmentA

Download an item attachment to a local path, potentially overwriting it. Requires write permission and confirmation.

Inputs: itemId (required), shareId (required), outputPath (required), attachmentId (required), +1 more.

generate_item_totpB

Generate TOTP code(s) for an item by URI or selectors, optionally targeting a specific field.

Inputs: uri, field, itemId, output, +4 more.

generate_passphraseC

Generate a passphrase.

Inputs: count, numbers, separator, capitalize.

generate_random_passwordC

Generate a random password.

Inputs: length, numbers, symbols, uppercase.

generate_totpA

Generate a TOTP token from a secret or otpauth URI.

Inputs: secretOrUri (required), output.

injectC

Inject secrets from Proton Pass references into a template file.

Inputs: inFile (required), force, confirm, outFile, +2 more.

list_invitesA

List pending invitations accessible to the current authenticated user.

Inputs: cursor, pageSize.

list_item_membersC

List item members.

Inputs: itemId (required), shareId (required), output.

list_itemsB

List items for a vault or share with MCP pagination support for JSON output.

Inputs: cursor, output, sortBy, shareId, +4 more.

list_sharesA

List shares accessible to the current authenticated user.

Inputs: output, onlyItems, onlyVaults.

list_vault_membersA

List members for a vault by share ID or vault name.

Inputs: cursor, shareId, pageSize, vaultName.

list_vaultsA

List vaults accessible to the current authenticated user.

Inputs: output.

move_itemC

Move an item from one vault to another.

Inputs: itemId, confirm, itemTitle, toShareId, +4 more.

reject_inviteB

Reject an invitation token.

Inputs: inviteToken (required), confirm.

remove_item_memberC

Remove an item member.

Inputs: shareId (required), memberShareId (required), confirm.

remove_vault_memberC

Remove a member from a vault.

Inputs: memberShareId (required), confirm, shareId, vaultName.

runC

Run a command with Proton Pass secret references resolved in environment.

Inputs: command (required), confirm, envFiles, noMasking, +1 more.

score_passwordC

Score password strength.

Inputs: password (required), output.

search_itemsA

Search items by title with MCP pagination support for JSON output.

Inputs: query (required), field, match, cursor, +7 more.

set_default_vaultC

Set default vault by share ID or vault name.

Inputs: confirm, shareId, vaultName.

share_itemC

Share an item with a user.

Inputs: email (required), itemId (required), shareId (required), role, +1 more.

share_vaultC

Share a vault with a user.

Inputs: email (required), role, confirm, shareId, +1 more.

transfer_vaultB

Transfer vault ownership to a member.

Inputs: memberShareId (required), confirm, shareId, vaultName.

trash_itemC

Move an item to trash by selectors.

Inputs: agentReason (required), itemId, confirm, shareId, +2 more.

unset_default_vaultC

Unset default vault setting.

Inputs: confirm.

untrash_itemB

Restore an item from trash by selectors.

Inputs: agentReason (required), itemId, confirm, shareId, +2 more.

update_itemC

Update an item using selectors and field assignments.

Inputs: fields (required), agentReason (required), itemId, confirm, +3 more.

update_item_memberB

Update an item member role.

Inputs: role (required), shareId (required), memberShareId (required), confirm.

update_vaultC

Update a vault by share ID or vault name.

Inputs: newName (required), agentReason (required), confirm, shareId, +1 more.

update_vault_memberC

Update a vault member role.

Inputs: role (required), memberShareId (required), confirm, shareId, +1 more.

view_itemA

View a specific item by URI or selectors, optionally returning a specific field.

Inputs: uri, field, itemId, output, +4 more.

view_session_infoA

View current Proton Pass session/account summary from pass-cli info.

Inputs: no named parameters.

view_settingsA

View current Proton Pass CLI settings.

Inputs: no named parameters.

view_user_infoA

View Proton user profile/account details from pass-cli user info.

Inputs: output.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 47 tools

    Disambiguation4/5

    Most tools map to distinct resource-action pairs: vaults, items, members, invites, attachments, and utilities are clearly separated. A few boundary cases like create_login_item_from_template versus create_custom_item or list_shares versus list_vaults could cause minor confusion, but the descriptions generally resolve it.

    Naming Consistency4/5

    The dominant verb_noun snake_case pattern is consistent across the set: list_vaults, create_vault, trash_item, untrash_item, share_vault, and so on. The main deviations are generic single-verb tools like inject and run, plus verbose template-based creation variants, but the overall pattern remains predictable.

    Tool Count2/5

    47 tools is a very large MCP surface, beyond what is typically comfortable for agent tool selection. Many tools are narrowly scoped variants, such as eight item-creation tools and separate member-management clusters, which could potentially be consolidated without losing clarity.

    Completeness4/5

    The tool set covers the full password-manager workflow well: vault lifecycle, item lifecycle with trash/restore/permanent delete, sharing and invitations, member management, TOTP, password generation, and session/settings checks. Minor gaps like uploading or updating attachments keep it from being a 5, but agents can complete common workflows without dead ends.

    Maintenance

    ActivitySlowing
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables secure secrets management through the Doppler CLI via natural language interactions. Supports managing secrets, projects, configs, and environments across different Doppler workspaces.
      11
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      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.
      14
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with 1Password vaults and items via the op CLI, supporting vault listing, item lookup, password read/create/update/generate, and delete operations. Zero idle CPU usage and supports service account tokens for headless use.
      15 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables to manage 1Password resources including vaults, items, documents, users, groups, and more through the 1Password CLI, exposing 65 tools for comprehensive password management via natural language.
      -