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 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.

• 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.

• 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.

• Optional read-only mode. Set PASSWORDS_READONLY=true to drop all six 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 (intended for localhost testing only).

• App-password auth. Authenticates with a revocable Nextcloud app-password over HTTP Basic — never your real account password.

• Secrets never logged. Debug logging (DEBUG=1) writes only method + path to stderr. Credentials, session tokens, and secret fields are never logged, cached, or written to disk.

• Minimal dependencies. Only the official MCP SDK and zod. Networking uses Node's built-in fetch; requests carry a 30s timeout.

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: nextcloud-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 (12; 6 in read-only mode)

Read (always available):

Write (hidden when PASSWORDS_READONLY=true):

Install

Build a tarball and install it globally:

pnpm install
pnpm pack:tarball          # produces passwords-mcp-<version>.tgz
npm install -g ./passwords-mcp-0.2.0.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

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. They assert the config validation rules, the write-payload builders (hash computation and the merge that preserves untouched fields), the read-only gating, and — most importantly — that metadata projection and search never expose secret fields.

License

MIT — see LICENSE.

Related

• Nextcloud Passwords and its API reference

• Model Context Protocol

• @modelcontextprotocol/sdk