virlow-mcp
v3.133.0
Published
Local MCP server for Virlow Secure Notes: end-to-end-encrypted AI memories and notes for Cursor, Claude, Codex, and any MCP client.
Readme
virlow-mcp
A local MCP server that gives any MCP-compatible AI client (Claude Code, Claude Desktop, Cursor, Codex, and others) durable memory and note access backed by Virlow — with your data end-to-end encrypted the entire time.
What it is
virlow-mcp runs on your machine as a local process (npx -y virlow-mcp@latest, launched by your
AI client over stdio). It exposes tools for four things:
- Memories — short, durable facts ("the user prefers TypeScript", "this repo's CI runs on self-hosted runners") that any AI tool can add, search semantically, and recall across sessions and projects. Each memory is an ordinary encrypted note in your Memories folder, so you can read, edit, reorganise, and trash them in the Virlow app like anything else you have written.
- Notes — full read/write access to your existing Virlow notes: search, list, read,
create, update, move, star, archive, and trash, plus folder management and
get_backlinks(notes that link to a note, from encrypted link records).update_notealso acceptsprops(property id to typed value) andaliases(alternative titles a note answers to when linked). - Properties: typed fields on a folder's notes, the way a database column works:
list_propertiesreads a folder's definitions,define_propertyadds one (text, number, select, multiSelect, date, checkbox, url, or relation), andset_propertiessets values on a note by property name, taking option names rather than ids.list_folder_viewreads the whole folder the way the app's table shows it, one row per note and one column per property, with an optionalsortBy; it answers "which of these is in review" or "what has no owner" without reading a single note body. Definitions live in the folder's encrypted schema and values in the note's encrypted attrs, so the server sees neither. Properties ship in the Virlow app as of its epic 3, so what is written here is what the user sees in the note, the table, the board and the calendar. - Attachments: files on a note.
list_attachments,add_attachment,read_attachment,rename_attachment,move_attachment,delete_attachmentandrestore_attachment. Files are encrypted in this process before upload, the same way the app does it.add_attachmenttakestextorcontent_base64(up to 2 MB), orpath, an absolute path to a file on this machine (up to 35 MB).read_attachmentreturns text and small files inline, and withsave_towrites the decrypted file to disk instead; it never replaces an existing file unlessoverwriteis true.delete_attachmentmoves a file to the note's Recently deleted, whererestore_attachmentcan bring it back for 30 days.pathandsave_toexist only when this server runs on your machine over stdio (or--httpon loopback); the hosted connector and a non-loopback--httptake inline content only.
Everything is end-to-end encrypted, zero-knowledge: the encryption key is derived from your Virlow master password inside this local process and never leaves it. Every memory and note is encrypted on your machine before it is sent to the Virlow API — the server stores only ciphertext. Decryption happens only in this local process, in memory — no decrypted text is ever written to disk.
Your account credentials and master password are just as protected from the AI: they are entered exclusively into a local browser form served by this process, never passed through a tool call, and never seen by the AI model.
This is the local server, and that distinction is the whole security model
Every claim above is about this package, running on your machine. Virlow also offers a hosted connector: the same tools, served from Virlow's own servers, so a client can connect by URL with nothing installed. It is a genuinely different trust model, and the sentence "the key never leaves it" is the part that stops being true:
| | this local server | the desktop app | the hosted connector | | --- | --- | --- | --- | | where the key is derived | this process, on your machine | the Virlow app, on your machine | Virlow's API process | | who can read a decrypted note | this process | the app's process | this process, and Virlow's server | | what an unlock sends | nothing; the password stays local | nothing; the password stays local | your master password, over HTTPS | | what it takes to run | Node on your machine | the installed app | nothing | | session lifetime | 4 hours idle | follows the app's vault lock | 30 minutes idle |
The hosted connector is off by default on every account and has to be switched on in Virlow's settings. If you are reading this page, you are looking at the option that keeps the key on your own hardware — that is the reason to prefer it, and the reason this package exists.
See SECURITY.md in the Virlow repository for what the hosted mode does and does not
guarantee.
Install / configure
virlow-mcp needs no separate install: npx -y virlow-mcp@latest fetches and runs it directly.
Add it to your client's MCP config:
Claude Code
claude mcp add virlow -- npx -y virlow-mcp@latestOn Windows, npx is a batch script, so wrap it in cmd /c:
claude mcp add virlow -- cmd /c npx -y virlow-mcp@latestRun that from PowerShell or cmd. Git Bash rewrites /c into a path; there, edit
~/.claude.json so the server's "command" is "cmd" and its "args" are
["/c", "npx", "-y", "virlow-mcp@latest"].
Claude Desktop
Add to your claude_desktop_config.json
(macOS: ~/Library/Application Support/Claude/claude_desktop_config.json,
Windows: %APPDATA%\Claude\claude_desktop_config.json):
{
"mcpServers": {
"virlow": {
"command": "npx",
"args": ["-y", "virlow-mcp@latest"]
}
}
}Cursor
Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-local):
{
"mcpServers": {
"virlow": {
"command": "npx",
"args": ["-y", "virlow-mcp@latest"]
}
}
}Codex CLI
Codex's MCP config is TOML, not JSON. Add to ~/.codex/config.toml:
[mcp_servers.virlow]
command = "npx"
args = ["-y", "virlow-mcp@latest"]Self-hosting Virlow
By default virlow-mcp talks to https://api.virlow.com. If you run your own Virlow API,
point it there with an env block (JSON clients) or env table (Codex's TOML), e.g. for
Claude Desktop / Cursor:
{
"mcpServers": {
"virlow": {
"command": "npx",
"args": ["-y", "virlow-mcp@latest"],
"env": { "VIRLOW_API_URL": "https://api.your-domain.com" }
}
}
}Connecting through the Virlow desktop app
If you run the Virlow desktop app, it already hosts this server on your machine and unlocks with the app. Clients that can send a header connect to it directly; the app shows the exact snippet under Settings, This computer. Clients that can only spawn a command use this package as a pipe:
{
"mcpServers": {
"virlow": {
"command": "npx",
"args": ["-y", "virlow-mcp@latest", "--connect", "http://127.0.0.1:47821/mcp",
"--token-file", "<path the app shows you>"]
}
}
}In this mode nothing is decrypted in this process. It forwards to the app and back.
Staying up to date
With virlow-mcp@latest in the command, your client gets the newest release each time it
starts the server, so restarting the client (or opening a new session) is the whole update.
Without @latest, npx can keep running a copy it downloaded earlier; add @latest to an
existing config to fix that. Pin an exact version ([email protected]) only if you want
updates to wait for you. The desktop app updates itself and its built-in server, and the
hosted connector is updated on Virlow's side.
The server checks npm once at startup, and the status tool and the unlock page say when a
newer version exists. The request tells npm only that someone at your IP checked
virlow-mcp's version; it carries no account data. Turn it off with
VIRLOW_MCP_NO_UPDATE_CHECK=1.
First use
- Ask your AI client to run the
unlock_vaulttool. This opens a browser window pointed at a page served by the local virlow-mcp process — sign in with your Virlow account email/password (and 2FA code, if enabled) and enter your master password there. - Once the form succeeds, ask the AI to run
statusto confirm the vault is unlocked and which account it's unlocked as. - From then on,
add_memory,search_memory,search_notes, and the rest of the tools work normally until the vault locks again (see Security notes).
How memories are stored
Memories live in a single folder marked as your memories root — shown with a brain icon
in the app, and created by this process the first time you add one. Its subfolders are
namespaces: add_memory with namespace: "acme-api" files the memory under
Memories/acme-api, creating that subfolder if needed. Memories with no namespace sit in
the root and are visible to every namespace's searches.
Each memory is a code note holding YAML frontmatter above the fact itself:
---
source: claude-code
tags: [ui, preferences]
confidence: high
created: 2026-09-01T00:12:04.000Z
---
Prefers dark mode in every editor, including terminal themes.The note's title is the memory's label. Because it is a code note, the app opens it in a plain text editor rather than the rich-text one, so nothing reformats it behind your back and every field is yours to edit.
Everything about that is safe to change by hand:
- Edit the fact and the next search reflects it — the memory re-embeds automatically.
- Edit the metadata and the tools report your values.
- Break the YAML and nothing is lost: the memory is simply read as all fact and no
metadata, still searchable, and the next
update_memoryrewrites it cleanly. - Drag it to another subfolder and its namespace follows.
- Trash it and it stops being recalled, recoverable from Trash like any note.
Deliberately not in the frontmatter: the memory's id, its label, and its namespace. Those are the note's id, its title, and the folder it sits in — duplicating them would just give you two versions to keep in sync.
What each name is
Memories name the people, projects and other things they are about. What each name is (a
person, an event, a pet...), other names it goes by and a one-line note live in one more
encrypted note in the root, the entity registry (type: entities). It is not a memory
and never shows up as one. add_memory takes entities as {name, kind} and records the
kind; describe_entity sets kind, aliases and note; untyped_entities lists the names
that have no kind yet. Kinds: person, organization, project, tool, place, event, topic,
product, media, pet, group, goal, other.
Reaching your vault from a session that is not on this machine
By default virlow-mcp speaks stdio, so your AI client spawns it as a child
process and everything stays on one machine. --http serves the same tools
over HTTP instead, so a client that cannot spawn a local process — a cloud
coding session, another laptop — can reach this vault:
npx -y virlow-mcp@latest --http # loopback, random port
npx -y virlow-mcp@latest --http --port 8787 # pick the portIt prints the URL and the path to a bearer token, generated on first run and
stored 0600 at ~/.virlow-mcp/http-token. Every request must carry it:
Authorization: Bearer <token>Your vault does not move. The master key is still derived and held in this
process on your machine; unlock_vault still opens its form in your local browser.
Virlow's servers still see only ciphertext.
What does change: decrypted note and memory text now travels over that connection to whatever client you point at it. So:
- The listener binds
127.0.0.1by default.--hostwill bind elsewhere and warns loudly, because anyone who can reach the port and holds the token can read your decrypted notes. - It speaks plain HTTP, not HTTPS. On loopback that is fine. Off loopback it is not: your notes and the bearer token itself travel unencrypted, readable by anyone on the path. The token authenticates the caller; it does not protect the bytes.
- So to reach it from outside, put a TLS-terminating tunnel in front of it
(
cloudflared,ssh -R, Tailscale) rather than binding to0.0.0.0. That is a confidentiality requirement, not a convenience. - Treat the token like a password. Delete the file to rotate it; the next start mints a new one.
- While it is on loopback, requests must arrive addressed to
localhostor127.0.0.1. A web page cannot reach it by pointing a hostname it controls at your loopback address — see the DNS rebinding note below.
Which folders AI tools can see
Every folder in the Virlow app has an "Expose to MCP" switch — "Let the local AI assistant read & edit this folder and its subfolders. Off by default." This server now honours it. Until this version it did not, so the app was telling you something untrue: the switch saved a value that nothing ever read.
- A folder is visible when it or any ancestor is switched on, matching what the label promises. Turning a parent on opens everything beneath it.
read_noterespects it too. Knowing a note's id is not consent.- The Memories folder is exempt — this server creates it and it exists only for AI tools.
- A note in no folder is not visible: exposure is granted per folder, and nothing has granted it. File it into an exposed folder to include it.
- Shared workspaces. A workspace you own follows its own switch, and its notes are opened with the workspace key. A workspace someone else shared with you stays closed to this local server for now: its "Expose to MCP" switch is one value every editor of that workspace can set, so it is not your consent, and there is no per-member switch for the local server yet. (The hosted connector reports a per-member value and follows that.)
- The signing keys of the people who share workspaces with you are remembered
in
~/.virlow-mcp/known-signers-*.jsonthe first time they are seen. A key that later changes is refused, and the notes it covers are left out.
Filtering is never silent. Any result that withheld something says so, with the count and what to do about it:
(4 notes hidden in folders that are not exposed to MCP. Turn on "Expose to MCP"
in a folder's settings in the Virlow app to include it.)A shortened list is otherwise indistinguishable from an empty vault, and you would have no reason to suspect a setting. Since the switch is off by default, expect to see this until you turn some folders on — that is the setting working, not a fault.
Turning memories off
Memories are opt-in. The switch lives in the Virlow app under Settings → Security → AI memories, and it is off until you turn it on. With it off, every memory tool refuses:
AI memories are switched off for this account. Turn on "AI memories" in
Settings → Security in the Virlow app to use this tool.The setting is re-read from your account on every memory tool call, never cached for the session. Turning it on being slow would be an inconvenience; turning it off being slow would be a privacy control that does not work — you would switch it off, keep being recorded, and have no way to tell. If the account cannot be reached, the tools refuse rather than assume consent.
--no-memories additionally starts the server with the five memory tools
unregistered, so they do not appear in tools/list at all:
npx -y virlow-mcp@latest --no-memoriesUse it when you want a connector that structurally cannot touch memories,
regardless of the account setting. Notes tools, unlock_vault, lock, and status
are unaffected either way.
Suggested agent rules
Drop this into your client's persistent instructions (.cursorrules, CLAUDE.md,
Codex's AGENTS.md, etc.) so the AI uses memory proactively instead of only when asked:
You have Virlow memory tools. At the start of a task, call search_memory
with the task topic to recall relevant facts. When you learn a durable
fact about the user, their preferences, or this project (a decision, a
convention, a gotcha), store it with add_memory — one concise fact per
call, a short label describing it, and namespace set to the project name
for project-specific facts. Do not store secrets, credentials, or
transient details.Security notes
- What's stored where. The Virlow API stores only ciphertext: encrypted note titles
and content, memories included. The plaintext-looking
title/contentcolumns for encrypted notes hold a literal[ENCRYPTED]placeholder, not your data. No decrypted text ever touches disk — decryption happens in this process's memory only, per tool call, and is discarded when the vault locks. Folder names are the one exception, and always have been: they are stored in the clear, so a namespace name is visible to the server even though everything in it is not. - Embedding cache. Search vectors are cached in
~/.virlow-mcp/cacheso a session starts without re-embedding every memory. The file is a single AES-GCM blob under your master key — note ids and timestamps included — and its name is a hash of your user id. Without your master password it is unreadable, and if it cannot be decrypted (say after a password change) it is silently discarded and rebuilt. It holds vectors only, never the text they came from. - Credentials never reach the AI. Login, master password, and any 2FA code are typed
into the local browser form (served on
127.0.0.1with a random one-time nonce) and go straight from your browser to this process and the Virlow API. No tool call ever carries a password, and the AI model never sees one. The page is served with a content-security policy that permits no script at all, cannot be framed, and is never cached. - DNS rebinding. Loopback is not the boundary it looks like: a web page can be
made to send requests to
127.0.0.1that your browser treats as same-origin, by pointing a hostname the attacker controls at your loopback address. Both local listeners — the unlock form and--http— refuse any request that is not addressed tolocalhostor127.0.0.1, which is what a rebound request always fails. The--httplistener applies this only while it is on loopback:--hostis a deliberate choice, and a tunnel in front of it legitimately rewrites the address. - Auto-lock. The vault locks automatically after 4 hours of inactivity, and
immediately on explicit
lock. Locking discards the in-memory decryption key and all cached memories/notes; any further tool call fails until youunlock_vaultagain. An operation still in flight when the vault locks cannot write its results back in afterwards. - Model download. Semantic search over memories runs a small, public embedding
model (
Xenova/all-MiniLM-L6-v2, ~30MB of open ONNX weights, pinned to a fixed revision) entirely locally via@huggingface/transformers. It downloads once, on the first memory-tool call, into~/.virlow-mcp/models, and is reused after that. This model only ever processes your already-decrypted plaintext locally to produce a vector — it sends nothing anywhere. - Dedupe.
add_memorycompares the new fact's embedding against existing memories in the same scope (same namespace, or global). At cosine similarity ≥ 0.9 it updates the closest match in place instead of creating a duplicate, carrying that memory's existing metadata and creation date forward. Between 0.7 and 0.9 it stores the new memory and tells the agent which existing ones it resembles. Only the label and the fact are embedded — never the frontmatter, which is near-identical across every memory and would otherwise distort these thresholds. - Hidden notes. Hidden notes never appear in
list_notes/search_notesresults; they can still be read by exact id withread_note.
