Everkeep MCP server

Everkeep

Stop re-explaining yourself to your AI.

Everkeep keeps your notes, decisions and projects in one folder on your own server. Your AI assistant reads it when a chat starts and writes down what you worked out — so tomorrow's conversation picks up where today's ended. You decide what it may change; it can't delete or overwrite anything you haven't allowed.

Works with Claude and any MCP client · runs on Linux, Docker or Home Assistant

Your documents, too

Drop contracts, invoices, manuals, price lists and exported reports into the folder as they are — PDF, Word, Excel, PowerPoint, e-mails. Your AI reads them as text, searches all of them at once and tells you where it found the answer: "which contract has a 30-day payment term?" comes back with the file and the page. No uploading files into every chat, no copy-pasting; a new version of a file is read the next time it is needed. Scanned pages it looks at as images.

Files go into the folder by ordinary copying, like into any other folder: see putting your files in.

Quick start

This gets Everkeep running on your own computer with Docker and connects Claude to it. You need about ten minutes and no programming.

1. Install Docker. On Windows or macOS, install Docker Desktop and start it; wait until it says Docker is running. On Linux, install Docker Engine.

2. Start Everkeep. Open a terminal (on Windows: PowerShell; on macOS: Terminal) and paste the two lines for your system. The first creates the folder everkeep-notes in your home folder; that folder is where your notes will live. The second downloads Everkeep and starts it in the background; it starts again by itself after a reboot.

Windows (PowerShell):

mkdir $HOME\everkeep-notes
docker run -d --name everkeep --restart unless-stopped -p 127.0.0.1:3100:3100 -v "$HOME\everkeep-notes:/vault" -v everkeep-data:/data ghcr.io/st412m/everkeep:1.1.0

macOS or Linux:

mkdir -p ~/everkeep-notes
docker run -d --name everkeep --restart unless-stopped -p 127.0.0.1:3100:3100 -v "$HOME/everkeep-notes:/vault" -v everkeep-data:/data ghcr.io/st412m/everkeep:1.1.0

On Linux the folder must be writable by user id 1000. If the command id -u prints a different number, follow Docker: who owns the folder instead.

3. Protect your notes. One more line, in the same terminal:

docker exec everkeep everkeep policy set . --mode rev --trash

From now on Claude can create new files in the folder, but it can change an existing file only after reading it, so it never overwrites what it has not seen. Nothing is deleted: a file Claude discards goes into the folder .vault-trash inside everkeep-notes, and you can take it back from there.

4. Get your token. Everkeep made a secret token on its first start. Show it:

docker exec everkeep everkeep token

It prints two lines. The first is the secret path for claude.ai, the second the header for other clients:

/private_<token>/mcp
Authorization: Bearer <token>

Treat both like a password: whoever has them can read and change your notes.

5. Connect Claude.

• Claude Code on the same computer:

  claude mcp add --transport http everkeep http://127.0.0.1:3100/mcp --header "Authorization: Bearer <token>"
  

• Claude Desktop on the same computer: add the block from Claude Desktop to its config file and restart it.

• claude.ai in the browser, or the Claude apps: they connect from the internet, so Everkeep needs a public HTTPS address. Remote access shows two free ways, step by step. Then, in claude.ai → Settings → Connectors → Add custom connector, paste https://<your public address>/private_<token>/mcp.

6. Try it.

• Ask Claude: "Use Everkeep to create a file about-me.md with what you know about my current projects." The file appears in your everkeep-notes folder.
• Open the folder: on Windows, type explorer $HOME\everkeep-notes in the same PowerShell (or go to This PC → Users → your name → everkeep-notes); on macOS, type open ~/everkeep-notes in Terminal (or Finder → your home folder); on Linux, open your home folder in the file manager.
• Copy a contract, an invoice or any PDF or Word file into it, by dragging or copy and paste, as into any folder. Everkeep sees it at once; nothing needs restarting. Folders inside it are fine and useful: contracts/, projects/….
• Ask Claude: "Use Everkeep: what does the contract in my notes say about payment terms? Give the page."

To have Claude read your notes at the start of every chat, add a line like this in Settings → Account → Instructions for Claude, or to a project's instructions: "At the start of a chat, read /vault/about-me.md with Everkeep." Inside Docker your folder is /vault.

To change the rules for a folder, see Write policies.

What it is

Everkeep is an MCP server. MCP is the way AI clients such as Claude call tools on other machines. Everkeep's tools work on one directory tree, the vault: read, search, edit, move and discard files, read documents and PDFs, query SQLite databases read-only. Nothing outside the vault can be reached through it.

What the assistant may change is set per directory with write policies: a directory can be read-only, editable only by someone who has read the current version of a file, open to new files only, or free. There is no delete: discarding moves a file into a trash directory of its zone. The assistant cannot change the policies; you set them on the server.

It runs as one process, over HTTP for remote clients such as claude.ai and over stdio for local ones such as Claude Desktop.

What it looks like

The assistant lists a directory. The first line says what is allowed there:

Policy: overwrite=rev, trash=.vault-trash, auto-purge after 30 d — own marker (/vault/wiki/.vault-policy)

[FILE] .vault-policy
[DIR] .vault-trash
[FILE] decisions.md
[FILE] todo.md

It tries to overwrite todo.md without having read it, and is refused:

Error: Refused — policy "overwrite: rev": changing an existing file requires its current rev, which is 5db20d56. Nothing was written. Repeat the call with rev: "5db20d56".

It searches, gets line numbers and the file's rev, and edits one line:

/vault/wiki/todo.md · rev 5db20d56 · 212 lines
  148: - [ ] Check backup-rotation settings on the NAS

— 1 match(es) in 1 file(s) · scanned 37/37 files, 190 KB, 12 ms

Requirements

Docker	Docker Desktop (Windows, macOS) or Docker Engine (Linux); images for amd64 and arm64 (Raspberry Pi 4/5)
Linux without Docker	Node.js ≥ 22.17, poppler-utils (pdfinfo, pdftoppm), sqlite3
Home Assistant	OS or Supervised, through the ha-filesystem-mcp app
Disk	the Docker image is about 340 MB; the npm package with its dependencies about 48 MB
For claude.ai	a public HTTPS address: see remote access

Installation

Docker

The image ghcr.io/st412m/everkeep runs everkeep serve on port 3100 as user id 1000, with the vault at /vault and its own state (token, document cache) in the volume /data. The Quick start shows docker run; compose.example.yaml does the same with Docker Compose. Folder ownership, updates and building the image yourself: installation.

Linux without Docker

Install poppler-utils and sqlite3 with your package manager, then run it with npx:

npx --yes --package=everkeep everkeep serve --vault /home/me/notes

On first start it prints the token once; everkeep token shows it again. For a permanent everkeep command, a CPU without AVX (some Celeron, Atom and Pentium models) and a systemd service, see installation. Windows and macOS are not supported without Docker.

Home Assistant

Install the ha-filesystem-mcp app. It runs Everkeep with the vault under /media or /share and adds the Vault policies page to the sidebar.

Configuration

Settings come from flags, environment variables and an optional JSON file (EVERKEEP_CONFIG, else ~/.config/everkeep/config.json). The ones to know first:

Setting	Flag / variable	Default
vault	--vault, EVERKEEP_VAULT	none, required
host	--host	127.0.0.1
port	--port	3100
state_dir	EVERKEEP_STATE_DIR	~/.local/state/everkeep
token	--token-file, EVERKEEP_TOKEN	generated into <state_dir>/token

everkeep check-config prints what is in force and checks the tools Everkeep needs. Every key, the token rules and the request log: configuration.

Connecting

• claude.ai, Claude Desktop connectors, the Claude apps: Settings → Connectors → Add custom connector with https://<your-host>/private_<token>/mcp. The address must be public HTTPS: remote access.

• Claude Code: over HTTP with the Bearer header, or on stdio:

  claude mcp add --transport stdio everkeep -- npx --yes --package=everkeep everkeep --vault /home/me/notes
  

• Claude Desktop without a public address: Everkeep on stdio through Docker, see Claude Desktop.

• Cursor and other clients: the URL http://127.0.0.1:3100/mcp (or your HTTPS address) with the header Authorization: Bearer <token>, see installation.

There is no OAuth: the token is the only key. A wrong path gets an empty 404, a wrong Bearer token 401.

Tools

20 tools. Parameters and return formats: tools.

Reading

• read_text_file — a whole file, head/tail lines, or an offset/limit range with line count and rev; documents as numbered lines
• read_multiple_files — several whole files in one response
• read_media_file — image or audio as base64
• read_pdf_text — text of a PDF or a page range, numbered like read_text_file
• read_pdf_page — one PDF page rendered as JPEG

Searching

• grep_files — regex search of file contents, documents included; returns path, rev, line count and matching lines
• search_files — find files and directories by name

Writing

• write_file — create or overwrite a file
• edit_file — literal oldText replacement, or line-addressed edits guarded by rev
• create_directory — create a directory and its parents
• move_file — move or rename a file or directory; also restores from the trash
• copy_file — copy a file; the destination follows the rules of write_file
• trash_file — move a file into its zone's trash; there is no delete

Listing

• list_directory — entries of one directory, after the policy line
• list_directory_with_sizes — entries with file sizes, sorted by name or size
• directory_tree — tree view, two levels deep
• get_file_info — size, times and format, plus line count and rev for text files
• list_allowed_directories — the vault root

SQLite (read-only)

• sqlite_schema — DDL of every object, file pragmas, optional row counts
• sqlite_query — one SELECT/WITH/VALUES/EXPLAIN statement, with a row limit

The search-then-edit workflow is in search and edit, SQLite in sqlite.

Write policies

With no policies, any tool may write anywhere in the vault. A policy is a small file .vault-policy in a directory; it covers the directory and everything below it. Set it on the server:

everkeep policy set wiki --mode rev --trash --purge-days 30 --vault /home/me/notes
everkeep policy set raw --mode readonly --vault /home/me/notes

Mode	Effect
readonly	no writes, edits, moves in or out, or discards
rev	new files are free; changing, moving out or discarding an existing file needs its current rev
never	new files only; existing files cannot be changed
free	no checks

With Docker, run the same commands inside the container: docker exec everkeep everkeep policy show. In the Home Assistant app, use the Vault policies page in the sidebar. The trash, auto-purge and what a broken marker does: write policies.

Documents and formats

read_text_file and grep_files read PDF, Word, Excel, PowerPoint, OpenDocument, EPUB, FB2, RTF, HTML and mail files as numbered lines with page, sheet and slide markers; grep_files reports where a match is (L8 (p.1), L2 (sheet Data)). A scanned PDF has no text; the answer says which pages to read as images with read_pdf_page. Documents are read-only. Extracted text is cached outside the vault. Formats, limits and the cache: documents.

Limitations

• Linux only without Docker. Windows and macOS run it in Docker.
• No OAuth. The token in the path or the Bearer header is the only key.
• No delete. trash_file moves a file into a trash directory, and only in a zone that has one.
• SQLite is read-only and will stay so.
• Documents are read-only, and scans are not recognized as text (no OCR).
• Policies stop Everkeep's tools only. Anything else that writes to the folder — you, a sync job, a file share — does not see them.
• Clients cache the tool list. After an update that changes tools, an open conversation keeps the old list.

Troubleshooting

• Claude shows no Everkeep tools. Check that the container runs (docker ps), that the token in the URL or header is the current one (everkeep token), and for claude.ai that the HTTPS address answers from outside.
• Every write fails with EACCES. The vault folder is not writable by the user Everkeep runs as (user id 1000 in Docker).
• 400 / 401 / 403 / 404 / 405 / 406. 401: wrong Bearer token. 404: wrong path or token in the path. 403: a Host or Origin that is neither local nor in allowed_hosts, on a server listening on 127.0.0.1. 405: not POST. 406: the Accept header lists neither JSON nor event streams. 400: bad JSON, an unsupported protocol version, or request headers that disagree with the body.
• Every write is refused and listings print ⚠ Policy: BROKEN MARKER. A .vault-policy file is broken and locks its zone. Fix it with everkeep policy or by hand.

More: troubleshooting.

Security

• The token is a password. It is generated by the server, at least 32 characters, never logged; put TLS in front of any address that leaves your machine.
• Every path is confined to the vault, including through symlinks and on case-insensitive file systems.
• On 127.0.0.1 (the default without Docker) requests whose Host or Origin is not local are refused, which stops websites in your browser from reaching it.
• The token and the document cache live in the state directory, which must be outside the vault.
• grep_files runs in a child process killed after 10 seconds; documents are extracted in worker threads with a timeout and a memory cap; SQLite runs sqlite3 -readonly -safe.

More: security.

Links

• Documentation — installation, putting your files in, remote access, configuration, write policies, tools, search and edit, documents, sqlite, security, troubleshooting, internals
• Home Assistant app
• Changelog
• Issues: problems of the server here; problems of installing or running the Home Assistant app in ha-filesystem-mcp

License

MIT — by st412m.