Repository avatar
Other Tools
v0.1.1
active

keepassbox

io.github.psyb0t/keepassbox

Manage KeePass vaults, entries, and TOTP over MCP.

Documentation

KeePassBox

CI version license Docker Pulls

Put KeePass behind REST and MCP. Create a vault, rotate its master password, turn Argon2 up to 512 MiB, or grab a TOTP code from the terminal. You can open the same .kdbx in KeePassXC.

Contents

Quick start

Run this as your regular Docker user on Linux. You need Docker Compose, curl, and OpenSSL.

curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-keepassbox/main/install.sh | bash
keepassbox start

If your shell can't find the command, run ~/.local/bin/keepassbox start. Run keepassbox token to get the installer-generated bearer token. It can manage its owner's vaults, read passwords, and generate TOTP codes. REST is at http://localhost:8000/v1, and MCP is at http://localhost:8000/mcp.

The installer puts the Compose files and vaults in ~/.config/keepassbox/ by default and uses the published psyb0t/keepassbox:latest image. See the install guide to pin a version, change the port, or upgrade.

What it does

  • Create and unlock multiple vaults with a master password, a configured key file, or both.
  • Change the KDBX 4 cipher, KDF, Argon2 memory, iterations, parallelism, and compression. Rotate the password or key file separately.
  • Create groups, search entries, move or trash them, and edit passwords, notes, tags, protected fields, and small attachments.
  • Save a TOTP seed or URI inside an entry and return the current code and expiry.
  • Give each bearer token access to one owner's vaults. Restrict individual tokens with a custom scope list.

Ordinary edits preserve entry history. The API reference lists the supported operations and file formats.

Agent integrations

Connect a Streamable HTTP MCP client to http://localhost:8000/mcp and configure its bearer token. See MCP configuration.

openclaw skills install @psyb0t/docker-keepassbox
openclaw plugins install clawhub:@psyb0t/keepassbox

Configure KEEPASSBOX_URL and KEEPASSBOX_TOKEN for the OpenClaw bridge.

Documentation

Read the KeePassBox docs for install options, vault security settings, and the REST and MCP commands.

Development

make lint
make test
make sec
make build

The tests run in Docker with synthetic KDBX files. The engine tests check encrypted round trips and TOTP. Integration tests call both transports.

Sponsor

Sponsor on GitHub

Buy Me a Coffee

License

GPL-3.0. The vault engine uses PyKeePass.