kdbx MCP server

kdbx — per-project secrets in KeePassXC vaults, safe to hand an AI agent

kdbx keeps a project's secrets in a per-project, per-environment KeePassXC vault (KDBX4, unlocked by a key file only — no master password) and gets them into the tools that need them without kdbx ever printing them into a transcript, a log file, or your shell history. Discovery is automatic: kdbx walks up from your current directory to a committed .keepassxc.json pointer file, works out which environment is active, and takes it from there. The headline command is kdbx run -- , which resolves that environment's variable mappings and injects them into a child process' environment. It replaces .env files as the source of truth; the vault stays outside the repo, so there is nothing secret to accidentally commit.

Every install method below is live — the curl installer, Homebrew, go install, the

ghcr.io container image, and the signed release archives (SHA256SUMS + cosign, with

reproducible builds). The badge above tracks the current version.

Install

# curl installer — downloads the release archive, verifies its SHA-256, installs to
# ~/.local/bin (override with KDBX_INSTALL_DIR; pin with KDBX_VERSION=v0.3.1)
curl -LsSf https://raw.githubusercontent.com/yarrasys/kdbx/main/install.sh | sh

brew install yarrasys/tap/kdbx                    # Homebrew
go install github.com/yarrasys/kdbx@latest        # from source, needs Go 1.25+
docker run --rm ghcr.io/yarrasys/kdbx:latest --version   # container (FROM scratch)

Windows: download the windows archive from the releases page and put kdbx.exe on your PATH.

Building from source needs Go 1.25 or newer (the KDBX engine and golang.org/x/term both declare a 1.25 floor). Release binaries are static and impose no toolchain requirement on users.

Shell completions:

kdbx completion zsh  > "${fpath[1]}/_kdbx"
kdbx completion bash > /etc/bash_completion.d/kdbx
kdbx completion fish > ~/.config/fish/completions/kdbx.fish
kdbx completion powershell | Out-String | Invoke-Expression

Quick start

1. Commit a pointer file at the repo root. It names the project and its environments; it contains no secrets, so it is safe to check in.

{
  "project": "demo",
  "defaultEnv": "dev",
  "envs": {
    "dev": {},
    "prod": {}
  }
}

An empty env object is fine — kdbx derives the artifact paths from the project and environment name: /demo/dev.kdbx and /demo/dev.keyx, where is $KEEPASSXCDIR if set, else %LOCALAPPDATA%\keepassxc on Windows, else $XDGCONFIGHOME/keepassxc or ~/.config/keepassxc. Set vault and keyFile explicitly if you want them somewhere else; both accept a ${KEEPASSXCDIR} token and a leading ~.

2. Create the vault and its key file.

$ kdbx init
ACTIVE ENV: dev  vault=/home/you/.config/keepassxc/demo/dev.kdbx  (source: pointer)
created /home/you/.config/keepassxc/demo/dev.kdbx
KEYFILE: /home/you/.config/keepassxc/demo/dev.keyx — back this up; losing it makes the vault unrecoverable.

Shortened. The full README is on GitHub.