
Enpass Mcp
io.github.bitterdev由 GitHub 账号 bitterdev 发布v0.1.0更新于 Oct 24, 2026
MCP server for Enpass vaults: entries, passwords and TOTP/2FA codes, keychain-backed.
概览
本地 MCP 服务器,让助手解锁 Enpass 保险库并读取条目、密码、TOTP 验证码和附件。
- 可以做什么
- 列出已注册保险库,解锁或锁定,并查看文件夹同步状态
- 按查询词、类别或文件夹搜索和列出条目,不返回密码
- 读取完整条目、密码或当前 TOTP/2FA 验证码
- 列出条目的附件,并将附件解密导出到磁盘
- 开启写入后:创建或删除条目,并拉取较新的同步副本
- 适用场景
- 适合把凭据保存在 Enpass 中、希望助手在同一台机器上查询登录信息、同时填入密码和 2FA 验证码,或读取安全笔记与附件的场景,无需手动把机密粘贴到对话中。
- 运行要求
- 需要 Node.js 18 或更高版本以及本地 Enpass 6/7/8 保险库文件。须先在终端注册保险库并输入主密码,密码保存在操作系统钥匙串中(Linux 需要 GNOME Keyring 或 KWallet 等 Secret Service 提供程序)。通过 stdio 运行;可选变量 ENPASS_MCP_ALLOW_WRITES、ENPASS_MCP_CONFIG_DIR 和 ENPASS_MASTER_PASSWORD。
安装
在 SourceWeft 中
- 打开 控制台中的 Enpass Mcp,将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。
其他 MCP 客户端
参照 仓库 中的启动说明。
README
enpass-mcp
A Model Context Protocol (MCP) server that gives an AI assistant controlled, local access to your Enpass password vaults: unlock a vault, list vaults, and list and read entries. Creating and deleting entries is possible too, but switched off until you enable it.
Runs locally over stdio. Your Enpass vault never leaves your machine, and your master password never passes through the model: it is stored in your operating system's keychain and read directly by the server.
Why this is safe
- Master passwords live in the OS keychain (macOS Keychain, Windows Credential
Manager, Linux Secret Service), not in config files, not in environment variables,
and never as a tool argument. The
unlock_vaulttool deliberately takes no password parameter, so the password can never end up in the model's context or in logs. - The vault stays local. The server reads the encrypted
vault.enpassdbfile directly with SQLCipher. Nothing is uploaded anywhere. - Reads are explicit. Listing entries never returns passwords. Secrets are only
returned by
get_item/get_password, when you explicitly ask for them. - Read-only unless you say otherwise. Out of the box the server cannot change
anything: the writing tools are not even advertised. Set
ENPASS_MCP_ALLOW_WRITES=1to enable them (see Writing).
Entry passwords are, by design, returned to the assistant when you ask for them, so only connect this to an assistant and vaults you trust.
Requirements
- Node.js 18 or newer
- An Enpass 6 / 7 / 8 vault (
vault.enpassdb, SQLCipher format) - On Linux: a Secret Service provider (GNOME Keyring or KWallet) for password storage
Native dependencies (better-sqlite3-multiple-ciphers, @napi-rs/keyring) ship
prebuilt binaries for common platforms, so no compiler is required in the normal case.
Install
Register your vaults (do this once, in a terminal)
This is the secure step that keeps the master password away from the model. You run it yourself; the password is typed into a hidden prompt and stored in the OS keychain.
add-vault verifies the password can actually unlock the vault before saving it.
The vault file is usually found at:
If you sync via Dropbox / OneDrive / WebDAV, point --path at the synced copy.
Connect it to your assistant
The server speaks MCP over stdio. Point your MCP client at enpass-mcp serve.
Claude Desktop (claude_desktop_config.json):
If you did not run npm link, use the absolute path instead:
Claude Code:
Tools
With ENPASS_MCP_ALLOW_WRITES=1 three more tools appear (see Writing):
list_items / get_item work for every Enpass entry type (logins, credit
cards, secure notes, identities, etc.), not just logins, and return all fields.
A typical assistant flow: list_vaults → unlock_vault → list_items → get_password.
How it works
Enpass stores each vault as a standard SQLCipher database (vault.enpassdb). The raw
encryption key is derived from your master password (optionally combined with a
keyfile) and the 16-byte salt at the start of the file:
- PBKDF2-HMAC-SHA512, 100000 iterations (older vaults) or 320000 (newer vaults), the first 32 bytes used as the raw SQLCipher key
- opened with
cipher_compatibility4 (Enpass 6.8+) or 3 (older vaults)
The server tries these combinations automatically, so it works across Enpass vault versions. The derived key is kept in memory only, for the lifetime of the server process, and is never written to disk or returned to the model.
References: Enpass Security Whitepaper, hazcod/enpass-cli.
Per-item field encryption
Enpass encrypts every value flagged as "sensitive" a second time, underneath
SQLCipher, with a key that belongs to the entry rather than the vault. Fields
carrying that layer have itemfield.algo_version = 1:
Binding the AAD to the entry uuid is what makes a value unusable if it is copied into
another entry. Enpass did not re-encrypt existing entries when it introduced this
layer, so one vault mixes ciphertext and plaintext under the same algo_version; a
value is treated as encrypted only when it has the shape of a payload (pure hex, whole
bytes, longer than the tag on its own).
A value that looks encrypted but fails authentication is returned as null with
decryptionFailed: true, never as the raw column content: stored ciphertext is a
plausible-looking string, and handing that back would silently pass off a wrong secret
as a real one.
Two-factor codes (TOTP)
Entries with a one-time-password secret (stored by Enpass as an otpauth:// URI)
can produce a live 2FA code: get_otp returns the current 6-digit code and the
seconds until it rotates, and get_password includes the current code alongside the
password. This lets an assistant fill both the password and the 2FA prompt.
Attachments
Enpass keeps file attachments encrypted. Small files (up to 1 KB) sit inline in the
vault; larger files live in separate <uuid>.enpassattach SQLCipher files next to the
vault, each encrypted with its own key stored in the vault. export_attachment handles
both: it decrypts the file and, by default, writes it to disk and returns the path, so
it works for files of any size without pushing binary data through the model.
Two details of that format are easy to miss, and both were wrong here until they were measured against real vaults:
attachment.passwordis not a key blob. It holds the finished SQLCipher raw-key expression as text,x'<64 hex key chars><32 hex salt chars>', and has to be passed through verbatim. Hex-encoding it produces a key SQLCipher rejects, and every external attachment then fails with "file is not a database".- The stored payload is frequently a base64 data URI (
data:application/pdf;base64,...) rather than the file itself, so it has to be decoded. Writing those bytes straight to disk yields a text file with a.pdfname.attachment.sizecounts the stored bytes, which is why it is larger than the exported file for anything wrapped this way.
If you hit a vault whose attachments still do not decrypt, please open an issue with the
(non-secret) schema of your attachment table.
Attachments also do not travel inside the folder-sync container: Enpass drops the
.enpassattach files into the sync folder next to it. sync_pull fetches the ones this
machine is missing, and publishing a write copies local ones the sync folder lacks.
Existing files are never overwritten or removed in either direction.
Writing (opt-in)
Writing is switched off by default. A password vault is the last place where a tool
should be able to change data just because a model decided to, so the server starts
read-only and does not even list create_item, delete_item, add_attachment and
sync_pull until you turn them on:
Set it in the server's environment (in your MCP client config, or in the .env next to
vaults.json). Nothing else changes: reading works exactly the same either way.
Enpass must be closed while writing. The app keeps the database in memory and would write its own cached copy back over any change made underneath it. Every writing tool refuses to run while Enpass is open.
Earlier versions of this README claimed writing was impossible because recent vaults (schema version 6) crash Enpass when entries are inserted directly. The crash was real, the diagnosis was wrong. Three concrete rules make it work, all of them derived from what Enpass itself writes:
- Enpass never stores
NULL. The crash isEXC_BAD_ACCESSinstrlenon a null pointer: a column omitted from theINSERTdefaults toNULL, and the app callsstrlenon it. Every column is written explicitly, empty strings instead ofNULL. - A template has a fixed field set.
login.defaultalways carries the same nine fields, in the same order, with the same field uids, even when most are empty. Writing only the fields you happen to have a value for produces an entry the app cannot render. - The per-item key is reproducible.
item.keyis a 32-byte AES-256 key plus a 12-byte GCM nonce, stored ashex(ciphertext || tag)with the item UUID as additional authenticated data. Nothing in it is tied to Enpass internals, so a fresh random key per item is fine.
Verified end to end against a real vault: written, read back, decrypted to the original, deleted, synced in both directions, and Enpass opens the vault without crashing.
Attaching files
add_attachment takes a path, never base64 in the argument list, and stores the bytes
raw in the attachment's own encrypted database. Two rules come out of the same format
details as reading, and getting either wrong looks exactly like a corrupted file while
every byte in the vault is intact:
- Store the raw bytes, not a data URI. A payload of
data:;base64,...is handed out verbatim by the Enpass app, so the export is a text file with a.pdfor.jpegname.add_attachmentrejects such input instead of storing it. - Pass the key expression through unchanged. It is already the ASCII SQLCipher raw-key expression; hex-encoding it again produces "file is not a database".
The row is built from the columns the vault's attachment table actually has, because the
column set differs between vault generations, and every column gets an explicit value so
no NULL reaches Enpass.
Regression guard: npm test writes a payload containing 0x00 and invalid UTF-8
sequences, reads it back, and asserts the bytes are identical and stored unencoded.
Repairing attachments that were stored as a data URI
scripts/repair-data-uri-attachments.mjs decodes such payloads back into raw bytes. It is
a dry run unless --apply is given, refuses to run while Enpass is open, and checks the
decoded payload against the file signature its name implies before writing.
The bytes of an external attachment live in its own .enpassattach file, and folder sync
keeps a second copy of every one of those files in the sync folder. Repairing the
vault under the Enpass container therefore fixes one machine only. --sync-folders
repairs the shared copies too, and only ever writes a payload that decodes byte for byte
to what the local machine already holds.
Configuration
Master passwords are in the OS keychain; only non-secret data (vault names and paths)
is stored in a small vaults.json:
- macOS:
~/Library/Application Support/enpass-mcp/vaults.json - Windows:
%APPDATA%\enpass-mcp\vaults.json - Linux:
~/.config/enpass-mcp/vaults.json
Override the directory with ENPASS_MCP_CONFIG_DIR.
Environment variables:
Development
CI (GitHub Actions) creates a vault from scratch with real SQLCipher, seeds entries and attachments, then runs the full read-only test suite on Node 18/20/22.
Security notes and limitations
- Anyone who can talk to this MCP server can read every password in a vault once it is unlocked. Only connect trusted clients.
- The server does not implement Enpass sync, item history, or trashing.
- The server is read-only and never modifies a vault. Creating or editing entries is intentionally not supported, because direct database writes crash recent Enpass vaults (see Why there is no write support).
- This is an independent project and is not affiliated with or endorsed by Enpass.
License
MIT © Fabian Bitter
来源:README.md,提交 6c84468
工具
0版本历史
1- v0.1.0最新Sep 16, 2026
评分
已满足适用检查项的 50%
该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。
- 近 30 天内可连通25 分
请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。
- 已声明认证方式10 分
请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分
