keepassxc-mcp
# keepassxc-mcp
MCP server for [KeePassXC](https://keepassxc.org/). 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 |
|---|---|
| `status` | Reachable? Associated? Database hash + KeePassXC version |
| `associate` | First-time pairing (KeePassXC shows a confirm dialog) |
| `unlock` | Raise KeePassXC's unlock window when the database is locked |
| `get_logins` | Username/password/TOTP for a **URL** |
| `get_totp` | Current TOTP for an entry UUID |
| `set_login` | Create or update a login |
| `generate_password` | KeePassXC's generator |
| `get_database_groups` | Folder tree |
| `create_group` | New group/path |
| `lock_database` | Lock the open database |
Lookups are by **URL**, not title — that is a KeePassXC protocol limit, not this server's.
## 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
```bash
git clone https://github.com/preginald/keepassxc-mcp.git
cd keepassxc-mcp
uv sync --all-extras
```
Or without uv:
```bash
pip install -e '.[dev]'
```
## Hermes
```bash
hermes mcp add keepassxc \
--command uv \
--args --directory /ABS/PATH/TO/keepassxc-mcp run keepassxc-mcp
```
Restart 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-mcp
```
or `python -m keepassxc_mcp` from an environment that has the package installed.
## Environment
| Variable | Meaning |
|---|---|
| `KEEPASSXC_SOCKET` | Unix socket path (otherwise auto-detected) |
| `KEEPASSXC_HOST` / `KEEPASSXC_PORT` | TCP instead of Unix (for a forwarded socket) |
| `KEEPASSXC_MCP_IDENTITY` | Identity file path |
| `KEEPASSXC_DB` | Database path used by `unlock` (skips discovery) |
| `KEEPASSXC_DB_DIR` | Folder to discover the newest `.kdbx` in |
| `KEEPASSXC_BIN` | KeePassXC binary to launch for the unlock window |
| `KEEPASSXC_MCP_AUTO_UNLOCK` | `0` disables the automatic unlock attempt |
| `KEEPASSXC_UNLOCK_TIMEOUT` | Seconds to wait for unlock, default 120 |
| `KEEPASSXC_TIMEOUT` | 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
```bash
uv run pytest
```
Tests use an in-process fake KeePassXC. They never touch a real vault.
## Protocol
[keepassxc-browser protocol](https://github.com/keepassxreboot/keepassxc-browser/blob/develop/keepassxc-protocol.md)
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.