README

🔐keepassmcp🔐

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

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
• create_entry
• update_entry
• delete_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.

write tools never return a password or note body. create_entry creates missing groups from its slash-separated group path. update_entry changes only supplied fields, stores the previous entry in KeePass history and accepts null as a custom-property value to delete that property. delete_entry requires the exact UUID returned by a list or search call. every local mutation is written to a temporary database and atomically replaces the original only after KeePass has saved it successfully.

remote storage adapters can be connected without coupling keepassmcp to a cloud provider. set KEEPASS_SYNC_COMMAND to an executable accepting prepare|commit, the configured database identifier and a local materialization path. prepare must return {"database":"/local/file.kdbx"}; commit must persist that file or fail. KEEPASS_LOCAL_DATABASE optionally fixes the materialization path. keepassmcp serializes the complete prepare/read-or-write/commit transaction through a local lock.

tests

composer install
vendor/bin/phpunit

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