English Français العربية

io.github.dafarusd/keephaven-mcp

Official registry Search and web

Agent memory on your own Keephaven home server: files, append-only journal, search.

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package @dafarusd/keephaven-mcp
Claude Code 
claude mcp add keephaven-mcp -e 'KEEPHAVEN_URL=<KEEPHAVEN_URL>' -e 'KEEPHAVEN_TOKEN=<your keephaven_token>' -- npx -y @dafarusd/keephaven-mcp@0.1.0
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "keephaven-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@dafarusd/keephaven-mcp@0.1.0"
            ],
            "env": {
                "KEEPHAVEN_URL": "<KEEPHAVEN_URL>",
                "KEEPHAVEN_TOKEN": "<your keephaven_token>"
            }
        }
    }
}

Environment variables

  • KEEPHAVEN_URL required The box's memory API, e.g. http://keephaven-xxxx.local:8790
  • KEEPHAVEN_TOKEN required secret Agent token from Settings > Agents on the box

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. keephaven-mcp
  2. What the agent gets
  3. What the owner keeps
  4. Set it up
  5. Try it with no box
  6. Status, honestly
  7. Agent skill

keephaven-mcp

Your agent's memory, on a box in your house. An MCP server that gives an AI agent a long-term memory stored on a Keephaven, not on a vendor's server.

Works with MCP clients that run local servers, like Claude Desktop, Claude Code and Cursor.

What the agent gets

ToolWhat it does
memory_writeSave a file, like people/dafarus.md or projects/keephaven.md. Optional etag check so two sessions don't overwrite each other.
memory_readRead a file back, with its etag.
memory_listList files, optionally under a folder.
memory_searchCase-insensitive search across files and journal.
memory_deleteDelete a file.
journal_appendAdd an entry to an append-only journal. The agent can add to it, never edit or delete it.
journal_readRead recent journal entries, oldest first.
memory_statusName, read-only or not, quota used.

What the owner keeps

  • Each agent gets its own folder and can't see any other agent's.
  • You add an agent in Keephaven's Settings > Agents and get a token, shown once. The box stores only a fingerprint of it.
  • Revoke cuts the agent off at once. Its files stay until you delete them.
  • Set a size limit per agent, or make one read-only.
  • If your Keephaven backs up to a second box, the agent's folder is part of that backup, and the backup box refuses every delete. That part isn't tested between two real boxes yet.

Set it up

  1. On the Keephaven: Settings > Agents > Add an agent. Copy the two values it shows.
  2. Add the server to your MCP client. For Claude Desktop, in claude_desktop_config.json:
{
  "mcpServers": {
    "keephaven": {
      "command": "npx",
      "args": ["-y", "github:dafarusd/keephaven-mcp"],
      "env": {
        "KEEPHAVEN_URL": "http://keephaven-xxxx.local:8790",
        "KEEPHAVEN_TOKEN": "khm_..."
      }
    }
  }
}

For Claude Code:

claude mcp add keephaven -e KEEPHAVEN_URL=http://keephaven-xxxx.local:8790 -e KEEPHAVEN_TOKEN=khm_... -- npx -y github:dafarusd/keephaven-mcp

It installs straight from GitHub, so the first start takes a minute while it builds. Needs Node 20 or newer.

The machine running the agent has to reach the box: same home network, the Keephaven's own Wi-Fi, or your Tailscale tailnet when Remote access is on.

Try it with no box

The box runs one Python file with no dependencies. Run that same file anywhere with Python 3:

python3 agent-memory.py serve --data ./mem --bind 127.0.0.1 --dev-token khm_try-it-locally

Then point the MCP server at http://127.0.0.1:8790 with that token. The file is modules/agent-memory.py in the Keephaven repo.

Status, honestly

  • The memory service is built and tested: 22 API tests, and a two-VM NixOS test where the service runs as its own locked-down user and a second machine uses it over the network.
  • This MCP server has 7 end-to-end tests: the official MCP client, this server over stdio, and the real memory service.
  • It ships in Keephaven Agent Memory, released 2026-10-25 for a Pi 5 and for a USB SSD on a Windows PC: https://keephaven.co/agent-memory. The Pi edition passed its release checks on one Pi 5, the SSD edition on a real drive on a Windows PC. Backup ran from a real Pi 5 (pre-release build) to a PC build in a VM over Tailscale — not yet between two real boxes. Home and Photos boxes don't have it.
  • Tokens travel in plain HTTP on your home network, like the rest of the box's local pages. Over Tailscale they're encrypted.

Agent skill

skill/keephaven/ is an agent skill (a SKILL.md plus a read-only check.py): how to use a Keephaven as memory, and how to boot one in a VM and report what works. check.py was run against the Photos SSD image booted in QEMU: setup page, then ready, Photos up, Immich 3.0.3.

Built by @Dafarusd. MIT License.

Frequently asked questions

What is io.github.dafarusd/keephaven-mcp?

Agent memory on your own Keephaven home server: files, append-only journal, search.

How do I install io.github.dafarusd/keephaven-mcp?

It runs on your machine. In Claude Code: claude mcp add keephaven-mcp -e 'KEEPHAVEN_URL=<KEEPHAVEN_URL>' -e 'KEEPHAVEN_TOKEN=<your keephaven_token>' -- npx -y @dafarusd/keephaven-mcp@0.1.0. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.dafarusd/keephaven-mcp need an API key?

Yes. It expects KEEPHAVEN_URL, KEEPHAVEN_TOKEN, which you set in its configuration.

Is io.github.dafarusd/keephaven-mcp open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains io.github.dafarusd/keephaven-mcp?

It is published by dafarusd. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.