kdbx — Claude Code MCP server: secrets and setup
kdbx gives an agent read access to secrets in a local KeePassXC vault and runs commands with environment variables injected. Secret values stay out of shell history.
claude mcp add --env KEEPASSXC_DIR=<KEEPASSXC_DIR> --env KDBX_ENV=<KDBX_ENV> --transport stdio kdbx -- docker run -i --rm -e KEEPASSXC_DIR -e KDBX_ENV ghcr.io/yarrasys/kdbx:0.3.2What kdbx does
kdbx connects a project to a KeePassXC vault through a .keepassxc.json file in the repository. The file defines environments and maps environment variables to vault entries. The secrets themselves stay outside the repository.
The kdbx run -- <cmd> command passes the mapped values to a child process alongside its existing environment. The MCP server gives the agent read-only access to secrets. You need a KeePassXC vault and its key file; if that key file is lost, the vault cannot be recovered, so keep a backup.
What it helps with
- pass secrets to a process without an
.envfile - run tests with variables from a KeePassXC vault
- separate project secrets by environment
- give an agent read access to project secrets
Example prompts for the agent
- Run the project tests with secrets from the active kdbx environment.
- Read the vault entry mapped to
OPENAI_API_KEYwithout displaying its value.
How to install kdbx
Platform CLI
claude mcp add --env KEEPASSXC_DIR=<KEEPASSXC_DIR> --env KDBX_ENV=<KDBX_ENV> --transport stdio kdbx -- docker run -i --rm -e KEEPASSXC_DIR -e KDBX_ENV ghcr.io/yarrasys/kdbx:0.3.2Replace <…> with your own values
Platform CLI
codex mcp add kdbx --env KEEPASSXC_DIR=<KEEPASSXC_DIR> --env KDBX_ENV=<KDBX_ENV> -- docker run -i --rm -e KEEPASSXC_DIR -e KDBX_ENV ghcr.io/yarrasys/kdbx:0.3.2Replace <…> with your own values
Config file
{
"mcpServers": {
"kdbx": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"KEEPASSXC_DIR",
"-e",
"KDBX_ENV",
"ghcr.io/yarrasys/kdbx:0.3.2"
],
"env": {
"KEEPASSXC_DIR": "<KEEPASSXC_DIR>",
"KDBX_ENV": "<KDBX_ENV>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"kdbx": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"KEEPASSXC_DIR",
"-e",
"KDBX_ENV",
"ghcr.io/yarrasys/kdbx:0.3.2"
],
"env": {
"KEEPASSXC_DIR": "<KEEPASSXC_DIR>",
"KDBX_ENV": "<KDBX_ENV>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e KEEPASSXC_DIR=<KEEPASSXC_DIR> -e KDBX_ENV=<KDBX_ENV> kdbx docker run -i --rm -e KEEPASSXC_DIR -e KDBX_ENV ghcr.io/yarrasys/kdbx:0.3.2Replace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about kdbx
How do I install kdbx in Claude Code?
Add the server with `claude mcp add --env KEEPASSXC_DIR=<KEEPASSXC_DIR> --env KDBX_ENV=<KDBX_ENV> --transport stdio kdbx -- docker run -i --rm -e KEEPASSXC_DIR -e KDBX_ENV ghcr.io/yarrasys/kdbx:0.3.2`. Replace the placeholders with your directory and environment.
What does kdbx do?
It lets an agent read secrets from a local KeePassXC vault. Commands run with the mapped environment variables, while secret values stay out of shell history.
What does kdbx need to work?
It needs a local KeePassXC vault, its key file, and a project .keepassxc.json file. Keep a backup of the key file; losing it makes the vault unrecoverable.
