Skip to main content
Glama
keepassxc-mcp

keepassxc-mcp

by preginald

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

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.

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

Or without uv:

pip install -e '.[dev]'

Hermes

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

uv run pytest

Tests use an in-process fake KeePassXC. They never touch a real vault.

Protocol

keepassxc-browser protocol

Available Tools

10 tools
associateA

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

    A3.6/5.0

    Scored across 10 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      MCP 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.
      32
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server for the Nextcloud Passwords app, enabling reading and managing password entries (list, search, create, update, delete) with strong security guarantees.
      14
      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