passwords-mcp
This MCP server lets you read and manage entries in a Nextcloud Passwords vault when client-side encryption is disabled.
Check connectivity and confirm CSE is off with
ping.List all passwords or filter by folder, returning metadata only.
Search passwords by label, username, or URL, returning metadata only.
Reveal a single password’s plaintext secret, notes, and custom fields by id.
List folders or fetch one folder by id.
Create, update, soft-delete, and restore passwords.
Create, update, soft-delete, and restore folders.
Use read-only mode to expose only the six read tools and refuse all writes.
Preserve fields on update, avoid blanking data, and never retry writes automatically.
Provides tools for reading and managing entries in a Nextcloud Passwords vault, including listing and searching password metadata, retrieving individual secrets, and creating, updating, deleting, and restoring passwords and folders.
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., "@passwords-mcp find my GitHub password"
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.
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_passwordsandsearch_passwordsreturn metadata only (label, username, URL, folder, timestamps). The plaintext secret, notes, and custom fields are stripped at a single choke point (toPasswordMeta). Onlyget_password, called with one specific id, ever returns a secret. Folder results pass through the equivalenttoFolderMetaallowlist.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_foldermove 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_folderare 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_passwordfetches the current entry, merges only the fields you passed, and sends the currentrevision— 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:hiddenon passwords, andhidden+favoriteon 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=trueto 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 setALLOW_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 theAuthorizationheader, and therefore the app-password, to whatever host theLocationheader 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,
DEBUGincluded, 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_URLis rejected if it embeds credentials, a query string, or a fragment;NEXTCLOUD_USERis 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.pingreads nothing. Connectivity is proved with the session handshake andsession/keepalive. It deliberately avoidspassword/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-infetch; requests carry a 30s timeout, and no retry wait can exceed 30s regardless of whatRetry-Afterasks 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? |
| Connectivity check; confirms CSE is off. Reads no vault data | No |
| All entries as metadata (optionally filtered by folder) | No |
| Metadata for entries matching a label/username/URL substring | No |
| A single entry incl. plaintext password, notes, custom fields | Yes |
| All folders | No |
| A single folder | No |
Write (hidden when PASSWORDS_READONLY=true):
Tool | Does |
| Create an entry (label + password required; username/url/notes/folder/favorite/hidden/customFields optional) |
| Change specific fields of an entry by id (merge; others preserved) |
| Move an entry to the trash (reversible; refuses if already trashed) |
| Take an entry back out of the trash (refuses if not trashed) |
| Create a folder (label required; optional parent/favorite/hidden) |
| Rename, re-parent, or change favorite/hidden state of a folder by id |
| Move a folder and its contents to the trash (reversible; refuses if already trashed) |
| 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.tgzThis 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 |
| yes | Instance base URL (no trailing slash). Must be |
| yes | Nextcloud username. |
| yes | A dedicated app-password. |
| no | Set to |
| no | Set to any value to log method, path, status and a correlation id to stderr (never secrets or response bodies). |
| no | Set to |
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/favoritesurvive an unrelated editcustom-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 throwingMCP 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,GETforsession/close, and re-open on a 412retry policy: reads retry, writes never do, and
Retry-Afteris parsed strictly and clampedpingnever requestspassword/listwith
DEBUGon, no response body or session token reaches stderr
License
MIT — see LICENSE.
Related
Available Tools
14 toolscreate_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_folderADestructive
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_passwordADestructive
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_folderARead-only
Fetch a single folder by its id.
Inputs: id (required).
get_passwordARead-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_foldersARead-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_passwordsARead-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.
pingARead-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_passwordsARead-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_folderADestructive
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_passwordADestructive
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
Scored across 14 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
The official Planning Center MCP server for interacting with your ministry's data.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for sovereign AES-256-GCM backup encryption and decryption. Enables encrypting, decrypting, verifying, and scoring passphrases with zero network calls.MIT
- AlicenseNot gradedqualityCmaintenanceLocal, encrypted password vault with AES-256-GCM and PBKDF2, exposing MCP tools for secure credential management, password generation, and search.MIT
- AlicenseAqualityCmaintenanceProvides local, secure access to Enpass password vaults via MCP. Enables unlocking vaults, listing entries, retrieving passwords, TOTP codes, and attachments, with optional write support.1074 npm3MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for accessing Vaultwarden servers with multi-account support.1MIT