npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

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_note also accepts props (property id to typed value) and aliases (alternative titles a note answers to when linked).
  • Properties: typed fields on a folder's notes, the way a database column works: list_properties reads a folder's definitions, define_property adds one (text, number, select, multiSelect, date, checkbox, url, or relation), and set_properties sets values on a note by property name, taking option names rather than ids. list_folder_view reads the whole folder the way the app's table shows it, one row per note and one column per property, with an optional sortBy; 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_attachment and restore_attachment. Files are encrypted in this process before upload, the same way the app does it. add_attachment takes text or content_base64 (up to 2 MB), or path, an absolute path to a file on this machine (up to 35 MB). read_attachment returns text and small files inline, and with save_to writes the decrypted file to disk instead; it never replaces an existing file unless overwrite is true. delete_attachment moves a file to the note's Recently deleted, where restore_attachment can bring it back for 30 days. path and save_to exist only when this server runs on your machine over stdio (or --http on loopback); the hosted connector and a non-loopback --http take 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@latest

On Windows, npx is a batch script, so wrap it in cmd /c:

claude mcp add virlow -- cmd /c npx -y virlow-mcp@latest

Run 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

  1. Ask your AI client to run the unlock_vault tool. 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.
  2. Once the form succeeds, ask the AI to run status to confirm the vault is unlocked and which account it's unlocked as.
  3. 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_memory rewrites 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 port

It 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.1 by default. --host will 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 to 0.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 localhost or 127.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_note respects 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-*.json the 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-memories

Use 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/content columns 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/cache so 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.1 with 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.1 that 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 to localhost or 127.0.0.1, which is what a rebound request always fails. The --http listener applies this only while it is on loopback: --host is 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 you unlock_vault again. 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_memory compares 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_notes results; they can still be read by exact id with read_note.