🔐keepassmcp🔐

keepassmcp is a PHP helper and MCP server that reads a local KeePass database — entries, notes, custom properties and passwords.

it is read-only by design: nothing in the database is ever written or changed.

keepassmcp requires PHP 8.5 or newer and Python 3 with pykeepass. the decryption itself is delegated to pykeepass because no PHP library reads KDBX 4.x reliably; every KDBX variant, including Argon2 key derivation, is therefore supported.

installation

composer require vielhuber/keepassmcp
pip install pykeepass

configuration

copy .env.example to .env or provide the same variables through the process environment:

KEEPASS_DATABASE=/path/to/passwords.kdbx
KEEPASS_PASSWORD_FILE=/dev/shm/keepass.pass
MCP_TOKEN=

the master password can be given either directly as KEEPASS_PASSWORD or, preferably, through a file named in KEEPASS_PASSWORD_FILE. a file keeps the password out of the process environment, where it would otherwise be inherited by every child process and stay readable in /proc/<pid>/environ. whichever channel is used, the value is dropped from the environment as soon as it has been read, and it is handed to the reader through stdin so it never appears in a process argument.

KEEPASS_PYTHON optionally points at a specific interpreter, for example one inside a virtualenv.

PHP

use vielhuber\keepassmcp\keepassmcp;
$vault = new keepassmcp();
$vault->listEntries();
$vault->searchEntries('api-key');
$vault->getEntry('7f9c…');

MCP server

vendor/bin/mcp-server.php

available tools:

• list_entries
• search_entries
• get_entry

list_entries and search_entries never return a password, a note body or a custom field value; they report titles, group paths, usernames, urls, the names of the custom fields and the flags has_password and has_notes. search_entries does look inside notes and inside the names and values of custom fields, so an entry stays findable by a mail address or an account number kept there. only get_entry returns the confidential values of a single entry, and its optional fields parameter narrows the answer — ["notes"] returns the notes without the password.

tests

composer install
vendor/bin/phpunit

the test suite uses a fake reader and never opens a real database.