Skip to main content
Glama
passwords-mcp

passwords-mcp

by megamaced

passwords-mcp

A Model Context Protocol server for the Nextcloud Passwords app. It lets Claude and other MCP-compatible clients read and manage entries in your Nextcloud password vault — listing/searching by metadata, revealing a single secret on request, and creating, updating, and (reversibly) deleting and restoring passwords and folders.

⚠️ This project is 100% AI-written. All source code, tests, CI configuration, and this documentation were written by AI (Claude). Review it yourself before pointing it at a real password vault. It is provided as-is, with no warranty (see LICENSE).

🔓 Requires client-side encryption (CSE) to be OFF. This server only works with accounts where the Passwords app's client-side (end-to-end) encryption is disabled. See Encryption requirement below.

Security model

This is a password-manager bridge, so it is built defensively even though it can now write:

  • Reads never bulk-expose secrets. list_passwords and search_passwords return metadata only (label, username, URL, folder, timestamps). The plaintext secret, notes, and custom fields are stripped at a single choke point (toPasswordMeta). Only get_password, called with one specific id, ever returns a secret. Folder results pass through the equivalent toFolderMeta allowlist.

  • Search ignores secrets. Searching matches on label / username / URL only — never on the password, notes, or custom fields.

  • Deletes are soft and reversible. delete_password / delete_folder move items to the trash. They first fetch the item and refuse if it is already trashed, so this server can never permanently delete anything — empty the trash from the Passwords app if you really mean it. restore_password / restore_folder are the undo; they only lift an item out of the trash and never roll an entry back to an older revision.

  • Updates never blank data. update_password fetches the current entry, merges only the fields you passed, and sends the current revision — so an edit can't silently wipe fields, and the server rejects the write if the entry changed underneath it. This includes fields the API would otherwise reset to their defaults: hidden on passwords, and hidden + favorite on folders, are carried across every update.

  • Writes are never retried automatically. A 5xx or a network failure on a create/update/delete proves nothing about whether the server applied it, so the tool reports an explicit unknown-outcome error instead of replaying the request — a retried create would duplicate an entry, and a retried revision-guarded write would report a false conflict. Reads are still retried with capped, jittered backoff.

  • Optional read-only mode. Set PASSWORDS_READONLY=true to drop all eight write tools from the tool list and refuse them at dispatch (defence in depth).

  • HTTPS enforced. Plaintext http:// is refused unless you explicitly set ALLOW_INSECURE_HTTP=true, and even then only for a loopback host (localhost, 127.0.0.0/8, ::1) — the opt-in can never send credentials to a remote host in the clear.

  • Redirects refused. Requests are made with redirect: 'error'. Following a redirect would hand the Authorization header, and therefore the app-password, to whatever host the Location header names. The Passwords API never legitimately redirects, so any 3xx is a hard failure.

  • Error responses are discarded unread. A Passwords API error body can echo the request that failed, so it is drained and thrown away without ever being inspected. A failure surfaces the status code, a static hint and a random correlation id — to the model and to the log alike. There is no configuration, DEBUG included, that routes a response body anywhere.

  • App-password auth. Authenticates with a revocable Nextcloud app-password over HTTP Basic — never your real account password. NEXTCLOUD_URL is rejected if it embeds credentials, a query string, or a fragment; NEXTCLOUD_USER is rejected if it contains a colon or control characters.

  • Secrets never logged. Debug logging (DEBUG=1) writes the method, path, status and correlation id to stderr. Credentials, session tokens, response bodies, and secret fields are never logged, cached, or written to disk — a test asserts this with debugging on.

  • ping reads nothing. Connectivity is proved with the session handshake and session/keepalive. It deliberately avoids password/list, whose default model would pull every decrypted password, note and custom field into this process.

  • Custom fields are validated, not passed through. They are accepted as structured objects and serialized centrally against the documented API limits, so a malformed or oversized blob can never be written into the vault. Limit violations report lengths, never values.

  • Minimal dependencies. Only the official MCP SDK and zod. Networking uses Node's built-in fetch; requests carry a 30s timeout, and no retry wait can exceed 30s regardless of what Retry-After asks for.

None of this removes the underlying risk: an app-password that can read and write the vault gives any connected client the same power — reading every secret and modifying entries. Scope and rotate the app-password accordingly, and use PASSWORDS_READONLY=true if you only need lookups.

Related MCP server: secret-vault-mcp

Encryption requirement

The Nextcloud Passwords app supports two encryption modes:

  • Server-side encryption (SSE) — encrypted at rest; the server holds the keys and returns plaintext to any authenticated session. Supported.

  • Client-side encryption (CSE) — end-to-end encryption gated by a master password the server never sees. Not supported.

This server implements none of the CSE (E2E) cryptography. On startup of each session it asks the server whether a challenge is required (session/request); if CSE is enabled it refuses to run with a clear error rather than returning ciphertext. To use this server, disable client-side encryption in the Passwords app settings.

Tools exposed (14; 6 in read-only mode)

Read (always available):

Tool

Returns

Secret?

ping

Connectivity check; confirms CSE is off. Reads no vault data

No

list_passwords

All entries as metadata (optionally filtered by folder)

No

search_passwords

Metadata for entries matching a label/username/URL substring

No

get_password

A single entry incl. plaintext password, notes, custom fields

Yes

list_folders

All folders

No

get_folder

A single folder

No

Write (hidden when PASSWORDS_READONLY=true):

Tool

Does

create_password

Create an entry (label + password required; username/url/notes/folder/favorite/hidden/customFields optional)

update_password

Change specific fields of an entry by id (merge; others preserved)

delete_password

Move an entry to the trash (reversible; refuses if already trashed)

restore_password

Take an entry back out of the trash (refuses if not trashed)

create_folder

Create a folder (label required; optional parent/favorite/hidden)

update_folder

Rename, re-parent, or change favorite/hidden state of a folder by id

delete_folder

Move a folder and its contents to the trash (reversible; refuses if already trashed)

restore_folder

Take a folder back out of the trash (refuses if not trashed)

Every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so clients can tell a metadata read from a secret disclosure or a vault mutation in their confirmation UI. They are hints for presentation — the read-only enforcement above is what actually blocks writes.

Writable fields

customFields replaces the entire set on an entry, so send the complete list rather than a delta. Fields are { label, type, value }, where type is one of text, secret, email, url, file, or data.

Tags are out of scope. The API leaves tags untouched when the field is omitted, which is what this server does. Editing them would need tag-discovery tools (list/create tags) that do not exist here, and sending a partial list would silently drop tags the model never saw.

Install

Build a tarball and install it globally:

pnpm install
pnpm pack:tarball          # produces passwords-mcp-<version>.tgz
npm install -g ./passwords-mcp-0.3.2.tgz

This installs the passwords-mcp command.

Configuration

Add to your MCP client config (Claude Code shown):

{
  "mcpServers": {
    "passwords": {
      "command": "passwords-mcp",
      "args": [],
      "env": {
        "NEXTCLOUD_URL": "https://your-nextcloud.example.com",
        "NEXTCLOUD_USER": "your-username",
        "NEXTCLOUD_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

Generate the app-password in Nextcloud under Settings → Security → Devices & sessions → "Create new app password". The server only needs an app-password, never your real account password — and you can revoke it at any time without affecting your main login.

Environment variables

Variable

Required

Description

NEXTCLOUD_URL

yes

Instance base URL (no trailing slash). Must be https://.

NEXTCLOUD_USER

yes

Nextcloud username.

NEXTCLOUD_APP_PASSWORD

yes

A dedicated app-password.

PASSWORDS_READONLY

no

Set to true to expose only the read tools and refuse all writes.

DEBUG

no

Set to any value to log method, path, status and a correlation id to stderr (never secrets or response bodies).

ALLOW_INSECURE_HTTP

no

Set to true to permit plaintext http:// for a loopback host only (localhost testing). Remote hosts are refused regardless.

Development

pnpm install
pnpm dev        # stdio MCP server; point the MCP inspector at it
pnpm test       # unit tests (config validation + secret-stripping guarantees)
pnpm lint       # eslint
pnpm typecheck  # tsc --noEmit
pnpm build      # tsc -> dist/

The unit tests are pure and need no server (global fetch is stubbed where a request is exercised). They assert:

  • metadata projection and search never expose secret fields — the core guarantee

  • the config validation rules

  • the write-payload builders: hash computation, the merge that preserves untouched fields, and that hidden/favorite survive an unrelated edit

  • custom-field validation and round-tripping

  • read-only gating, and that unknown tool names — including ones inherited from Object.prototype — return a tool error rather than throwing

  • MCP annotations are present and correct on every registered tool

  • session handling: one handshake under concurrent first calls, replay of the most recent X-API-SESSION, GET for session/close, and re-open on a 412

  • retry policy: reads retry, writes never do, and Retry-After is parsed strictly and clamped

  • ping never requests password/list

  • with DEBUG on, no response body or session token reaches stderr

License

MIT — see LICENSE.

Available Tools

14 tools
create_folderB

Create a new folder. Requires a label; parent folder id is optional.

Inputs: label (required), hidden, parent, favorite.

create_passwordA

Create a new password entry. Requires a label and the secret value; username, url, notes, folder id and favorite are optional. Stored with server-side encryption (cseType none).

Inputs: label (required), password (required), url, notes, +5 more.

delete_folderA
Destructive

Move a folder AND ITS CONTENTS to the trash (reversible, soft delete). Refuses if the folder is already trashed, so it can never permanently delete.

Inputs: id (required).

delete_passwordA
Destructive

Move a password to the trash (a reversible, soft delete — restore it from the Passwords app). Refuses if the entry is already trashed, so it can never permanently delete anything.

Inputs: id (required).

get_folderA
Read-only

Fetch a single folder by its id.

Inputs: id (required).

get_passwordA
Read-only

Reveal a SINGLE password entry by its id, including the plaintext secret, notes and any custom fields. This exposes sensitive credentials — only call it for a specific id the user has asked to see, never to bulk-export. Get ids from list_passwords or search_passwords.

Inputs: id (required).

list_foldersA
Read-only

List all folders (id, label, parent folder id, timestamps). Folders hold no secret material. Use a folder id with list_passwords to filter.

Inputs: no named parameters.

list_passwordsA
Read-only

List saved passwords as METADATA ONLY (id, label, username, url, folder, timestamps). The secret value is never included — use get_password with a specific id to reveal one. Optionally filter by folder id.

Inputs: folder.

pingA
Read-only

Verify connectivity to the configured Nextcloud Passwords instance: that the URL and app-password work, the Passwords app is installed, and client-side encryption is disabled. Reads no vault data.

Inputs: no named parameters.

restore_folderA

Restore a trashed folder, undoing delete_folder. Only takes the folder out of the trash — it never rolls it back to an older revision. Reports an error if the folder is not in the trash.

Inputs: id (required).

restore_passwordA

Restore a trashed password, undoing delete_password. Only takes the entry out of the trash — it never rolls the entry back to an older revision. Reports an error if the password is not in the trash.

Inputs: id (required).

search_passwordsA
Read-only

Search saved passwords by a case-insensitive substring of their label, username or URL. Returns METADATA ONLY (no secret values). Use get_password with an id from the results to reveal a single secret.

Inputs: query (required).

update_folderA
Destructive

Rename a folder, move it under a different parent, or change its favorite/hidden state, by id. Fields you do not pass keep their current value. Hiding a folder also hides everything inside it.

Inputs: id (required), label, hidden, parent, +1 more.

update_passwordA
Destructive

Update fields of an existing password by id. Only the fields you pass are changed; all others — including hidden/favorite state and custom fields — are preserved (the server rejects the write if the entry changed underneath us). Note that customFields REPLACES the whole set. Tags are left untouched and cannot be edited through this server. Provide at least one field besides id.

Inputs: id (required), url, label, notes, +6 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool targets a distinct action on a distinct resource (password vs folder) with clear separation between metadata-only listing, search, and secret-revealing get. The restore/delete pairs are unambiguous, and ping stands alone. No two tools overlap in purpose.

    Naming Consistency5/5

    All tools follow a consistent verb_noun snake_case pattern (list_passwords, get_password, create_folder, restore_password, etc.). The only deviation, 'ping', is a standard health-check verb that fits the style. Naming is predictable and uniform.

    Tool Count5/5

    14 tools cover the full password and folder lifecycle (CRUD + restore + search + metadata listing) without bloat. Each tool serves a necessary function and the count matches the domain scope well.

    Completeness5/5

    The server provides complete coverage for password and folder management: create, read (metadata and secret), update, delete (soft with restore), plus search and folder hierarchy operations. No obvious gaps; bulk export is intentionally omitted for security, and all required actions are supported.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for sovereign AES-256-GCM backup encryption and decryption. Enables encrypting, decrypting, verifying, and scoring passphrases with zero network calls.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Local, encrypted password vault with AES-256-GCM and PBKDF2, exposing MCP tools for secure credential management, password generation, and search.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Provides local, secure access to Enpass password vaults via MCP. Enables unlocking vaults, listing entries, retrieving passwords, TOTP codes, and attachments, with optional write support.
      10
      74 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for accessing Vaultwarden servers with multi-account support.
      1
      MIT