@appsoftwareltd/etherpk-mcp

An MCP server that gives an AI agent (Claude Code, Codex, Cursor and others) one of your EtherPK knowledge graphs. It runs on the agent's computer. The agent can search your notes by words or by meaning, follow links, list tasks, and read and edit documents without breaking EtherPK's format.

This package is EtherPK's Headless Client, EtherPK without an editor. It serves a graph folder on your computer or a graph synced through a Sync Server, with the same tools for both. Protected documents are never shown to the agent, not even by name; graph_info only counts them.

Needs Node.js 24 or later.

Get started

A synced graph

In EtherPK, open the graph's Settings → Agents and select Create an Agent Setup Code. The tab shows two commands with your server, the code and the graph filled in. On your own Sync Server, the tab links to the server's Access tokens page, which makes the code.

# Once per computer. When this terminal and EtherPK, on a device where your Encryption Keys are
# unlocked, show the same code, approve there, then press y here.
npx @appsoftwareltd/etherpk-mcp login --sync-server https://sync.etherpk.com --code <Agent Setup Code>

# Register the graph with your agent (Claude Code shown, the Agents tab has the others).
claude mcp add --scope user etherpk -- npx @appsoftwareltd/etherpk-mcp serve --sync-server https://sync.etherpk.com --graph <graph id>

A local graph folder

No sign-in and no Sync Server:

claude mcp add --scope user etherpk -- npx @appsoftwareltd/etherpk-mcp serve --folder /path/to/your/notes

The folder must already be an EtherPK graph, with pages/ and journals/ folders in it. EtherPK makes them when it opens a folder, and the agent skill makes them for a new one. Settings → Agents shows this command with the path filled in once the folder's path is set on the General tab.

Ask about your notes

The server describes its tools and the graph to the agent, so nothing else needs setting up. To make the agent always use them, add a line like this to your CLAUDE.md, or your agent's equivalent:

My notes are stored in EtherPK. Use the etherpk MCP tools for anything I've written down, and search in semantic mode for questions.

What the agent can do

Thirty-six tools, the same for a synced graph and a folder. Each serve serves one graph, and no tool shows a protected document: a read answers as if there were no such document, and a write onto its name is refused.

A synced graph's tools answer from this computer's copy. While that copy cannot reach the Sync Server, every answer ends with a note saying since when, and graph_info reports connection. Edits made elsewhere since then are not in the answer.

read_asset, read_theme and preview_theme write only in the graph's downloads folder in the cache directory, and import_theme_folder reads only from there. A folder outside it is refused, so a prompt hidden in a note cannot steer the agent into writing or reading elsewhere.

Several agents on one graph

Any number of agents can use one graph at once. The first serve for a graph starts a background process that holds the graph, and every serve passes its agent's requests to it, so there is one copy of the graph in memory and one index on disk.

• The agent's session starts at once. A tool called before the graph has opened waits for it.
• The process saves the graph and stops five minutes after its last agent has gone (ETHERPK_MCP_HOST_IDLE_SECONDS). An agent still connected starts a new one on its next request.
• running lists the processes with their agents and logs, and stop ends them.
• If the process stops during a request, the agent is told the request may or may not have been applied. A request that never reached it goes to the next process.
• With no graph to serve (not logged in, or a folder that is not a graph yet), the agent stays connected and each tool answers graph_unavailable with the reason. A request 10 seconds or more later tries again, so fixing the cause needs no restart.
• The process logs to host.log in the graph's cache directory. publish runs in the same process.

Search by meaning

search matches words. After one setup step it also matches meaning, so "when do I pay my taxes" finds the note that says "due 31 January". A small embedding model runs on this computer. Nothing is sent anywhere, and protected documents are never embedded.

npx @appsoftwareltd/etherpk-mcp semantic setup

Setup installs a native runtime of about 300 MB (through your npm) and a 23 MB model into the cache directory, once per computer.

• No restart. A graph's background process checks every 30 seconds and starts embedding once setup has run. Until then a search by meaning is refused, and the message names the setup command.
• Modes. search takes mode: "semantic", or "hybrid" for words and meaning together. Each result has the document, its breadcrumb of headings and parent bullets, the passage and a similarity score.
• Progress. The first pass over a large graph takes minutes and runs in the background. After that only changed documents are embedded. Results report embedded, total and complete, and semantic status shows each cached graph.
• When it runs. Only while the graph's background process runs, which is while an agent has the graph open and for five minutes after. To keep a graph current without an agent, run npx @appsoftwareltd/etherpk-mcp serve --graph <id> </dev/null & (or --folder <path>).
• Load. The model uses a quarter of the cores, at most four, and pauses a tenth of a second between batches. ETHERPK_MCP_SEMANTIC_THREADS changes the thread count. Set it in the agent registration's env.
• Per agent. serve --no-semantic keeps one registration text-only.

Synced graphs

Signing in

login makes this computer a device of your account.

• The token. --code trades an Agent Setup Code for an Agent Token. Create the code in EtherPK's Agents settings (the Graphs page's Agents tab, or a synced graph's Settings → Agents), or on the Sync Server's Access tokens page, where the token is then listed as "Agent on ". An agent token can read and write your graphs. It cannot reset or replace your Encryption Keys, make tokens, invite people or delete graphs. It stops working after 30 days unused, when you revoke it, and when you reset your Encryption Keys.
• For a script, --pat or ETHERPK_PAT gives an account-wide access token instead. login unlocks with it, then swaps it for an Agent Token and revokes it. If the swap fails, login fails and keeps nothing.
• The keys are unlocked by Device Approval. Open EtherPK in a browser where the account's Encryption Keys are unlocked. When the browser and the terminal show the same short code, select Approve in the browser and press y in the terminal. Press n if the codes differ.
• Without EtherPK to hand, press r while login waits, or pass --recovery-code, and type your Recovery Code. ETHERPK_RECOVERY_CODE supplies it for a scripted setup.

login then lists the graphs the account can reach.

Choosing a graph

graphs lists the synced graphs each signed-in account can reach, with the name, the id and your role. serve --graph takes the id or the name. (unnamed) means a graph has no name yet.

Several Sync Servers

Run login once for each Sync Server. --sync-server then says which server a command means. It can be left out while only one server is signed in.

Local folders

• The folder must hold pages/ and journals/. serve never creates them, so a mistyped path is refused rather than turned into an empty graph.
• Edits made in an editor, or by the agent writing files directly, are picked up before the next tool call, and the index follows within a second or so.
• A tool's write is in the file when the tool returns. A failed write is reported to the agent and retried on the next write.
• The index is kept in the cache directory, never in the folder. Moving or renaming the folder starts a new index.

Publishing a site

publish renders one publication of a graph into a folder on this computer and prints the report:

npx @appsoftwareltd/etherpk-mcp publish --graph <id or name> --publication <id> --out <dir>

• --out is remembered for that graph and publication. Later runs without it, and the agent's publish tool, write to the same folder.
• The top-level .html files, assets/, theme/ and the search and feed files are rewritten, and files that no longer belong are removed. Everything else in the folder is left alone.
• The folder must be one of its own, outside the graph's folder. A publish refuses the graph's folder, a folder inside it and a folder that holds it, because it would remove the graph's files.
• --dry-run in place of --out renders and checks the publication and prints the whole report, with the names of the pages it mentions, without writing anything. It needs no folder. Keep its output out of public logs. The agent's publish tool takes dryRun: true for the same check.
• Deploying the folder is up to you. Run the command from cron for a site that republishes itself.
• Mermaid diagrams, maps and Excalidraw drawings need a browser. A map is published as a picture of the map, drawn over EtherPK's map host unless ETHERPK_MAP_STYLE_URL names another style, and a drawing as a picture with its fonts inside it. diagrams setup installs a Chromium of about 170 MB into the cache directory, once per computer, and a publish whose pages hold any of them refuses until then. ETHERPK_CHROMIUM names a Chromium already on the computer instead, which NixOS needs.
• list_publications, or Settings → Publish in EtherPK, shows the publication ids.

To publish straight to a branch of a GitHub repository, as one commit that the host watching the branch deploys, give --github in place of --out, with a GitHub token that may read and write the repository's Contents:

ETHERPK_GITHUB_TOKEN=<token> npx @appsoftwareltd/etherpk-mcp publish --graph <id or name> --publication <id> --github <owner/name[#branch]>

• The branch is main unless #branch names another. A publish never creates the branch.
• --github is remembered in place of the folder, so later runs need only the token.
• A publish that changes nothing makes no commit. The first publish to a branch that already holds other files lists the files it would replace and stops, and --replace publishes anyway.
• The agent's publish tool never commits to a repository, because a commit can put the site live. It can check the publication with dryRun: true.

The agent skill

The etherpk agent skill teaches an agent to make a blog, docs site or wiki folder in EtherPK's format inside any project, to check it with publish --dry-run, and to publish it with this command. For a synced graph it sends the agent to the tools above. Install it in the project the agent works in, or with -g for every project:

npx skills add appsoftwareltd/etherpk-client

Reference

Every command is npx @appsoftwareltd/etherpk-mcp <command>. For the short form, etherpk-mcp, install the package globally once with npm install -g @appsoftwareltd/etherpk-mcp. --help (-h) prints the command reference and --version (-v) the version.

Commands

Flags

Environment variables

Set a variable that serve should see in the agent registration's env as well as your shell, because the agent starts serve with its own environment.

What stays on your computer

• The agent token and your Encryption Keys. They go in the system keychain where login can use one: the macOS Keychain, or a Linux desktop's keyring through secret-tool (the libsecret-tools package on Debian and Ubuntu). The login file, ~/.config/etherpk/mcp.json, then names only the server. Otherwise they are in the login file, readable only by your user, like a signed-in browser's storage. login says which. Any program running as you can ask the keychain for them, so run only agents you trust with your account, and never let one read, print or search ~/.config/etherpk.
• A cache of each synced graph you serve, under ~/.cache/etherpk/mcp/, so a restart fetches only what changed. It holds your notes readably. The Sync Server stays the source of truth, and a newer version of this package rebuilds a cache it can't read.
• For a folder, its index and, with semantic search, its embeddings, under local/<folder name>-<hash of its path>/ in the cache directory. Nothing is written into the folder.
• Beside each graph's cache, host.json while its background process runs, and host.log, which names the graph's documents and is deleted with the cache. The process listens on a socket in a directory only your user can open ($XDG_RUNTIME_DIR/etherpk-mcp, or etherpk-mcp-<uid> in the temporary directory), or on Windows on a named pipe with a random name.

On Windows the login file and the cache are under C:\Users\<you>\.config\etherpk\ and C:\Users\<you>\.cache\etherpk\.

To cut an agent off, revoke its agent token on the Sync Server's Access tokens page. logout revokes the token itself and deletes the keys and cached graphs on this computer. If the computer or its login file may have been copied, also select Replace Encryption Keys and lock out other devices in EtherPK, so the keys saved there no longer open your account.

Build from source

The package's source is apps/mcp in the etherpk-client repository. It compiles the Client's sync, crypto and index code in through a $lib alias, so it builds from the repository root, not from this folder alone:

pnpm install --frozen-lockfile
pnpm --filter @appsoftwareltd/etherpk-mcp check   # type check
pnpm --filter @appsoftwareltd/etherpk-mcp test    # unit tests, no server needed
pnpm --filter @appsoftwareltd/etherpk-mcp build   # dist/main.js, run with node dist/main.js

The repository's CI publishes each release to npm, at the same version as the Client. To check that a version is on the registry:

npx -y @appsoftwareltd/etherpk-mcp@<version> --version

Documentation and licence

The full guide is Using AI agents with your notes. What changed in each release is in the changelog, which covers this package and the EtherPK Client, released together under one version.

The package is available under the Elastic License 2.0 (LICENSE): you may use, copy, modify and self-host it, but not offer it to others as a hosted or managed service. It is source-available, not open source.