keepassxc-mcp
Provides access to a running, unlocked KeePassXC instance over its browser-integration socket, enabling lookup of logins (username/password/TOTP) by URL, retrieval of TOTP codes, creating or updating logins, generating passwords, browsing and creating groups, checking status/association, and locking the database.
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., "@keepassxc-mcp get the login for https://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.
keepassxc-mcp
MCP server for KeePassXC. It talks to the running, unlocked app over the same browser-integration socket the Chrome/Firefox extension uses. Hermes (or any MCP client) can then look up and save credentials without copy-paste.
It never opens your .kdbx file and never asks for the master password.
What you get
Tool | Does |
| Reachable? Associated? Database hash + KeePassXC version |
| First-time pairing (KeePassXC shows a confirm dialog) |
| Raise KeePassXC's unlock window when the database is locked |
| Username/password/TOTP for a URL |
| Current TOTP for an entry UUID |
| Create or update a login |
| KeePassXC's generator |
| Folder tree |
| New group/path |
| Lock the open database |
Lookups are by URL, not title — that is a KeePassXC protocol limit, not this server's.
Related MCP server: passwords-mcp
Requirements
KeePassXC 2.7+ with Browser Integration enabled (Settings → Browser Integration)
Database unlocked
Python 3.10+
On this laptop the socket is already present when KeePassXC is running:
/run/user/$UID/org.keepassxc.KeePassXC.BrowserServer
Install
git clone https://github.com/preginald/keepassxc-mcp.git
cd keepassxc-mcp
uv sync --all-extrasOr without uv:
pip install -e '.[dev]'Hermes
hermes mcp add keepassxc \
--command uv \
--args --directory /ABS/PATH/TO/keepassxc-mcp run keepassxc-mcpRestart Hermes after adding. First real lookup pops a KeePassXC dialog named something like keepassxc-mcp — accept it once. The association is stored at ~/.local/share/keepassxc-mcp/identity.json (mode 0600).
Then: "get my GitHub login" or "save this API key in KeePassXC for https://api.example.com".
Other MCP clients
stdio command:
uv --directory /ABS/PATH/TO/keepassxc-mcp run keepassxc-mcpor python -m keepassxc_mcp from an environment that has the package installed.
Environment
Variable | Meaning |
| Unix socket path (otherwise auto-detected) |
| TCP instead of Unix (for a forwarded socket) |
| Identity file path |
| Database path used by |
| Folder to discover the newest |
| KeePassXC binary to launch for the unlock window |
|
|
| Seconds to wait for unlock, default 120 |
| Seconds (default 30; association waits up to 120) |
Locked database
Credential tools fail while the database is locked. unlock (and every other
tool, unless auto-unlock is off) tries D-Bus openDatabase first, then launches
KeePassXC so its window appears with a password box. You type the master
password there; this server never receives it.
D-Bus alone is not enough when KeePassXC is hidden in the tray — it accepts the call and shows nothing. That is why the launch fallback exists. Verified on KeePassXC 2.7.12 / Hyprland.
The launcher pins QT_QPA_PLATFORM=wayland and finds a live wayland socket.
Omarchy exports QT_QPA_PLATFORM="wayland;xcb"; with an unreachable X display
that fallback aborts KeePassXC inside QGuiApplication::createPlatformIntegration
before any window exists, so the unlock prompt can never appear.
Security
Secrets travel encrypted (NaCl box) between this process and KeePassXC, then as MCP tool results to the agent.
The agent will see passwords it fetches. Do not attach this server to an untrusted chat.
Writes still go through KeePassXC; it may prompt you.
Identity file is equivalent to a browser-extension pairing key. Keep it 0600 and local.
Tests
uv run pytestTests use an in-process fake KeePassXC. They never touch a real vault.
Protocol
Available Tools
10 toolsassociateA
Associate this MCP server with the unlocked KeePassXC database.
KeePassXC shows a confirmation dialog; the user must accept it. Usually needed only once — the association is stored locally for later sessions.
Inputs: no named parameters. Returns: result
create_groupC
Create a group (path, e.g. 'Root/MCP' or 'Work/API keys').
Inputs: group_name (required). Returns: result
generate_passwordA
Generate a password using KeePassXC's generator settings.
On some KeePassXC versions this opens the generator dialog and waits for the user to accept it.
Inputs: no named parameters. Returns: result
get_database_groupsA
List the group/folder tree of the unlocked database.
Inputs: no named parameters. Returns: result
get_loginsA
Look up saved credentials whose URL field matches.
KeePassXC's browser protocol matches on URL, not title. Pass a full URL such as https://github.com or https://console.aws.amazon.com. Returns username, password, name, uuid, and TOTP when present.
Inputs: url (required), submit_url. Returns: result
get_totpA
Get the current TOTP code for an entry UUID (from get_logins).
Inputs: uuid (required). Returns: result
lock_databaseB
Lock the currently open KeePassXC database.
Inputs: no named parameters. Returns: result
set_loginB
Save a new login, or update an existing one when uuid is provided.
KeePassXC may still prompt the user to confirm the write. Prefer generating the password with generate_password first rather than inventing one.
Inputs: url (required), login (required), password (required), uuid, +3 more. Returns: result
statusA
Report whether KeePassXC is reachable and this client is associated.
Inputs: no named parameters. Returns: result
unlockA
Ask KeePassXC to open a locked database, raising its unlock prompt.
The master password is typed by the user in the KeePassXC window; this server never sees it. Other tools call this automatically when they hit a locked database, unless KEEPASSXC_MCP_AUTO_UNLOCK=0.
Inputs: timeout. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool has a distinct role: association/status, unlock/lock lifecycle, group listing/creation, credential lookup/save, TOTP retrieval, and password generation. Although associate, unlock, and status all relate to database state, their descriptions clearly separate initial setup, user-driven unlock, and reachability reporting.
Most tools follow a clear verb_noun pattern such as generate_password, get_database_groups, create_group, get_logins, get_totp, set_login, and lock_database. The bare verbs associate/unlock and the noun status are minor deviations but remain readable and unambiguous.
Ten tools is well within the expected range for a focused KeePassXC integration. Each tool covers a distinct operation in the connection, database, group, credential, and TOTP workflows without obvious redundancy.
The surface covers setup, unlock/lock, group listing/creation, credential lookup/save, TOTP, and password generation, but lacks deletion operations for logins and groups, and has no group update/rename. These are notable gaps for managing a password database, though core retrieval and creation workflows are present.
Related MCP Connectors
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Browser MCP for logged-in tasks. Uses your Chrome — credentials stay local. Zero-token replay.
Read and write shared BitsWeave context, projects, tasks, and work sessions through MCP.
Manage your KeepMySubs subscriptions, spend, renewals, and bills from any MCP client.
Related MCP Servers
- AlicenseBqualityCmaintenanceMCP server for secure credential management, browser-based login automation, and TOTP/2FA auto-solving. Encrypts credentials with AES-256-GCM and automates login flows via Playwright.322MIT
- AlicenseAqualityBmaintenanceMCP server for the Nextcloud Passwords app, enabling reading and managing password entries (list, search, create, update, delete) with strong security guarantees.14MIT
- 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