kdbx

Name: kdbx
Author: yarrasys

by yarrasysversion 0.3.2i★ –iRuns on your computer

Registry nameio.github.yarrasys/kdbx

Install

Overview

Description from the maker (original English)

Read-only access to secrets in a local KeePassXC vault. Runs commands with them injected.

PopNx MCP’s three pillars

These three are never merged into one score: opinions, measurements and popularity are different things.

User voiceiNo reviews yetReviews open together with accounts in a later step
Our basic checksi1 of 1 passedChecked from public information; code not scanned yet
UsageiNot measured yet★ –

What you can do with it

We have not written a plain-language summary for this one yet. Below are the facts we read from the registry.

Connection: Runs on your computer
Transport: stdio
Category: Other

Install

Pick the AI app you use, then copy the settings.

Before you install

Basic checks: 1 of 1 passed
Runs on your computer with your user’s permissions (files, network, apps).
You fill in yourself: KEEPASSXC_DIR, KDBX_ENV

You need

DockerDocker installed

Which app do you use?

ClaudeClaude CodeCursorVS CodeChatGPT

Pick your app above. We remember it, so next time the button says “Install in …”.

Open Claude Desktop → Settings → Developer → Edit Config, and paste this into claude_desktop_config.json

{
  "mcpServers": {
    "kdbx": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "KEEPASSXC_DIR",
        "-e",
        "KDBX_ENV",
        "ghcr.io/yarrasys/kdbx:0.3.2",
        "mcp"
      ],
      "env": {
        "KEEPASSXC_DIR": "your-value",
        "KDBX_ENV": "your-value"
      }
    }
  }
}

Run this in your terminal

claude mcp add kdbx --env KEEPASSXC_DIR=your-value --env KDBX_ENV=your-value -- docker run -i --rm -e KEEPASSXC_DIR -e KDBX_ENV ghcr.io/yarrasys/kdbx:0.3.2 mcp

Fill in the empty values before running it.

Open in Cursor

Or copy the settings yourself

Paste into .cursor/mcp.json in your project, or ~/.cursor/mcp.json

{
  "mcpServers": {
    "kdbx": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "KEEPASSXC_DIR",
        "-e",
        "KDBX_ENV",
        "ghcr.io/yarrasys/kdbx:0.3.2",
        "mcp"
      ],
      "env": {
        "KEEPASSXC_DIR": "your-value",
        "KDBX_ENV": "your-value"
      }
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

Open in VS Code

Or copy the settings yourself

Paste into .vscode/mcp.json in your project

{
  "servers": {
    "kdbx": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "KEEPASSXC_DIR",
        "-e",
        "KDBX_ENV",
        "ghcr.io/yarrasys/kdbx:0.3.2",
        "mcp"
      ],
      "env": {
        "KEEPASSXC_DIR": "your-value",
        "KDBX_ENV": "your-value"
      }
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

This one runs on your computer, and ChatGPT can only connect to servers on the internet. Pick another app.

Your choice stays on this device in a cookie; no account needed.

Values you fill in

KEEPASSXC_DIR env
Where kdbx looks for vaults inside the container. Must match the mount target above.
KDBX_ENV env
Environment to select, overriding the pointer's defaultEnv. Optional.

These settings are generated from the maker’s registry entry. If the README says otherwise, follow the README.

What it can do

Runs on your computer; the tool list appears in your AI app after you install it.

Basic checksi

We check information anyone can see; we have not read the code. Checks that do not apply are left out of the count. · Checked Nov 7, 2026

✓ Pass
Maker matches the repo
The registry name was verified with the GitHub account yarrasys, which owns the repo
… Not checked yet
Still maintained
We have not read this repo from GitHub yet
… Not checked yet
Has a licence
We have not read this repo from GitHub yet
– Not applicable
Endpoint responds
This one runs on your computer; there is no internet endpoint
– Not applicable
Sign-in with OAuth
Runs on your computer and uses local settings instead
… Not checked yet
No hidden instructions in tool descriptions
Runs on your computer; we can only read tool lists from internet endpoints

Compared with others in Otheri

More stars than 0% of the other 32712 servers in this category
Published to the registry more recently than 61% of the other 32712 servers in this category
Basic checks equal to or better than 100% of the other 32712 servers in this category

Compared with every active server in this category in the registry. Stars count only when the publisher owns the repo.

Common questions

Is kdbx safe?

It passed 1 of 1 applicable basic checks. We have not read the code. Before adding a key or token, see what access the server asks for and use a key with only the permissions you need.

What keys or codes does it need?

The registry does not list a required key, though some servers ask you to sign in on first use.

Does it run on my computer or in the cloud?

It runs on your computer. Your AI app starts it when needed, and data does not pass through the maker’s servers (unless it calls an online service itself).

Is it still maintained?

The GitHub repo last changed –, and the latest version (0.3.2) reached the registry 24 days ago.

Which apps can use it?

Apps that support MCP, such as Claude Desktop, Claude Code, Cursor and VS Code. You also need Docker on your computer.

What can I use instead?

In the same category: Spec Driven Development, Remote Desktop Commander, Aiterm MCP

Alternatives

Servers in the same category from other makers, sorted by stars.

Reading a card:★ GitHub starsiThree pillars: reviews · checks · usageiUpdated = latest version published to the registryi

Spec Driven Development

by formulahendry

MCP Server that facilitates spec-driven development workflows, not just Vibe Coding.

Runs on your computer★ 440MITUpdated 14 months ago

Install

Remote Desktop Commander

by desktop-commander

Remote Desktop Commander: use files, terminal and processes on your own computers from any AI app.

Runs in the cloud★ 211Updated 2 days ago

Install

Aiterm MCP

by kitepon

Persistent terminals and one launcher for Claude, Codex, Grok, Cursor, and Antigravity harnesses.

Runs on your computerUpdated today

Install

README from the maker

Open the README

Copied from the maker’s repo as written. PopNx MCP has not reviewed or endorsed it. HTML, images and scripts are removed. Links lead off this site.

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.2)

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.26+ 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.26 or newer. Go 1.25 left support when Go 1.27 shipped, and current golang.org/x/term releases declare a 1.26 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 $KEEPASSXC_DIR if set, else %LOCALAPPDATA%\keepassxc on Windows, else $XDG_CONFIG_HOME/keepassxc or ~/.config/keepassxc. Set vault and keyFile explicitly if you want them somewhere else; both accept a ${KEEPASSXC_DIR} 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.

3. Store a secret and map it to an environment variable. The value never appears on the command line — it arrives on stdin, from --from-env, or from an interactive prompt.

$ kdbx set api/openai --var OPENAI_API_KEY < secret.txt

ACTIVE ENV: dev vault=/home/you/.config/keepassxc/demo/dev.kdbx (source: pointer) modified tracked file .keepassxc.json — review and commit

--var records the mapping in the pointer file, preserving existing key order so the diff stays reviewable:

"dev": {

"vars": { "OPENAI_API_KEY": "api/openai" } }

4. Run something with the secrets injected.

kdbx run -- claude              # the author's actual daily use

kdbx run -- npm test kdbx --env prod run -- ./deploy.sh

The child inherits your environment plus the mapped variables. Its exit code is passed straight back out. Nothing is written to disk, and the value never appears in your shell history.

Reading is deliberately boring:

$ kdbx list

api/openai $ kdbx get api/openai (set, hidden) $ kdbx check # every mapping still resolves → exit 0, no output $ kdbx envs

dev prod

Operations

Every operation accepts --env NAME. Read operations additionally accept --json. Operations marked ✦ print the banner ACTIVE ENV: vault= (source: ) to stderr; pure display operations do not.

Op	Flags	Behavior (stdout / stderr / exit)
`init` ✦	`--here`, `--mode standard\	strict`	create vault + key file; with no pointer anywhere above, or with `--here`, first writes a fresh `.keepassxc.json` in the current directory (project named after it, `dev`/`prod` envs, `dev` active) so starting a project is one command; inside another project's tree, plain `init` names the pointer file it is about to use and asks for confirmation first (TTY only, exit 4 otherwise), pointing at `--here` as the way to start a separate project; stderr `created` plus a KEYFILE backup warning; refuses to overwrite an existing vault, key file, or pointer; `--mode` records the env's policy in the pointer, and `strict` anchors it into the new vault
`policy bless` ✦		anchor the pointer's current policy (its `policy` and `run.allow` sections) into the vault; interactive-only, like `rekey`, and denied to agents by the guard; strict `run` refuses until the anchor matches
`set PATH` ✦	`--var NAME`, `--from-env VAR`, `--raw`	value from `--from-env`, else an interactive prompt with confirmation on a TTY, else stdin (empty → error; one trailing newline stripped unless `--raw`); an empty or whitespace-only value is refused; `--var` adds the mapping to the pointer file
`get PATH`	`--reveal` \	`--clip`	default: prints `(set, hidden)` — no length or prefix leak; `--reveal` prints the value with a stderr warning; `--clip` copies it and auto-clears after ~15 s; missing entry or field → exit 2
`list [GROUP]`		sorted `group/…/title` lines, filtered by the `GROUP` prefix, Recycle Bin excluded; never prints values
`delete PATH` ✦	`--purge`	soft-deletes to the Recycle Bin by default; `--purge` prompts `y/N` (TTY only — a non-TTY refuses with exit 4) then removes permanently
`mv SRC DST` ✦		moves or retitles an entry, creating destination groups; re-points the active environment's var mappings that referenced `SRC`, keeping any `:field` suffix; stderr `re-pointed N var mapping(s) …`
`run` ✦	`--allow-missing`, `--no-mask`, `--any`, `-- CMD…`	if the pointer has a `run.allow` list, refuses an unlisted command before the vault is even opened (exit 7, `NotAllowed`) unless `--any`; resolves the active environment's `vars` map, injects it into the child's environment, resolves `argv[0]` through PATH (PATHEXT on Windows), forwards signals, and passes the child's exit code through; when a child stream is captured (not a TTY), injected values ≥ 8 bytes in it become `***` (`--no-mask` disables; the guard denies it for agents); no command → exit 2; an unresolved var → exit 5 unless `--allow-missing`
`export` ✦	`--out FILE`, `--allow-missing`	renders the mappings as dotenv (always double-quoted; `\`, `"` and newlines escaped); `--out` writes atomically at 0600 with a gitignore reminder, otherwise stdout
`import FILE` ✦		parses a dotenv file (no `$VAR` interpolation), stores each `KEY` at `imported/KEY` and registers the mapping; stderr reminds you to delete or rotate the source file
`check`		prints `MISSING VAR -> path` per broken mapping; exit 0 when clean, 5 on drift
`envs`		one line per environment, the active one marked `*` ; stderr `active: (source: )`; no pointer file → exit 2
`rekey` ✦		prompts `y/N` (TTY only, else exit 4), mints a new key file, re-keys the vault, replaces the old key file atomically; stderr reminds you to redistribute it

Integration surfaces:

Command	Purpose
`kdbx mcp`	read-only MCP server over stdio (five tools: `kdbx_list`, `kdbx_envs`, `kdbx_check`, `kdbx_get`, `kdbx_run`)
`kdbx guard --hook pretooluse`	evaluates a `PreToolUse` hook payload on stdin and denies agent-issued human-only operations
`kdbx completion`	emits a completion script for bash, zsh, fish, or powershell
`kdbx --version`	prints `kdbx`

`--json`

--json gives read operations a machine-readable stdout. Secret values are never included.

$ kdbx --json list

{"entries":["api/openai"]} $ kdbx --json envs {"envs":[{"name":"dev","active":true}],"source":"pointer"} $ kdbx --json check {"missing":[],"ok":true} $ kdbx --json get api/openai {"path":"api/openai","set":true}

--json with --reveal is rejected (exit 7). On failure, stdout carries {"error":{"op":"check","exit":5,"kind":"Drift"}} alongside the usual stderr line and exit code.

Entry paths

An entry path is group/sub/Title[:field]. The field defaults to password. The reserved field names — title, username, password, url, notes, matched case-insensitively — map to the KeePass entry's native attributes; anything else becomes a protected custom property. More than one :, an empty field after :, or an empty / segment is rejected. Variable names passed to --var must match ^A-Z_*$.

Environment selection

--env beats $KDBX_ENV, which beats the pointer's defaultEnv, which defaults to dev. kdbx envs and the banner report which of the three won. An environment that isn't in the pointer file is an error (exit 2).

Exit codes

Code	Meaning
`0`	success
`1`	generic failure (scrubbed)
`2`	not found — no pointer file, unknown environment, missing entry or field, no command given to `run`
`3`	locked, key file missing, or credential failure
`4`	a destructive operation was not confirmed
`5`	drift — `check` found a broken mapping, or `run`/`export` could not resolve one
`6`	the vault changed underneath a write; re-run
`7`	preflight rejection (e.g. an invalid `--var` name, or `--json --reveal`)

Failures print exactly one stderr line and never a stack trace or a secret. The line carries the stable kind plus kdbx's own message, which is written so that no secret value can ever appear in it:

$ kdbx get api/nope

kdbx: get failed: NotFound: entry not found: api/nope

The text of an underlying third-party error is never shown, since it is not under that rule. Set KDBX_DEBUG=1 to additionally get the full error chain and stack on stderr.

Environment variables kdbx reads: KDBX_ENV, KEEPASSXC_DIR, XDG_CONFIG_HOME, LOCALAPPDATA, KDBX_DEBUG.

Roles — agents read, humans write

kdbx is designed to be safe to hand to a coding agent. The rule is:

Agent-safe: run, get (masked), list, check, envs, init.
Human-only: set, delete, mv, import, rekey, export, and get --reveal / get --clip.

An agent can *use*

Only the beginning is shown; read the rest in the repo

kdbx

Overview

PopNx MCP’s three pillars

What you can do with it

Install

Before you install

Values you fill in

What it can do

Basic checksi

Maker matches the repo

Still maintained

Has a licence

Endpoint responds

Sign-in with OAuth

No hidden instructions in tool descriptions

Compared with others in Otheri

Common questions

Alternatives

Spec Driven Development

Remote Desktop Commander

Aiterm MCP

README from the maker

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

Install

~/.local/bin (override with KDBX_INSTALL_DIR; pin with KDBX_VERSION=v0.3.2)

Quick start

Operations

--json

Entry paths

Environment selection

Exit codes

Roles — agents read, humans write

`--json`