LINZA — Claude Code MCP server: a map of your notes folder
A local MCP server that indexes a Markdown folder and hands the agent topics, links and memory candidates. Writes wait for review.
claude mcp add --env LINZA_VAULT=<LINZA_VAULT> --env LINZA_EMBED_PROVIDER=<LINZA_EMBED_PROVIDER> --env LINZA_EMBED_URL=<LINZA_EMBED_URL> --env LINZA_EMBED_MODEL=<LINZA_EMBED_MODEL> --env LINZA_EMBED_KEY=<LINZA_EMBED_KEY> --transport stdio linza -- uvx linza-mcpWhat LINZA does
Point LINZA at a folder of notes and it builds a SQLite database next to it, at .linza/linza.db. The agent gets a working picture: how many notes were found, whether the index is fresh, which broad areas show up, which material shapes repeat, where documents look connected, and what might matter in later sessions. Indexing leaves your files alone.
Every change the server proposes goes through review. A dry-run comes first, then your confirmation, and only then a write into .linza or a compact YAML block. Approvals can be taken back: the record is marked revoked, stops counting as an active example, and stays in the history. The teach and grow steps pick good accepted examples and suggest similar intents, naming the rules that put them in the batch.
Python 3.10+ is required. A plain install covers Markdown, TXT, JSON, DOCX and XLSX; PDF reading needs the pypdf extra. Semantic search, the topic map and link suggestions depend on an embedding server, so without one those tools sit idle. Set the folder through LINZA_VAULT — leave it out and the server falls back to ./vault, which is a poor default for real notes.
What it helps with
- make sense of a notes folder that has grown too large
- spot which material shapes keep repeating
- surface likely links between documents and say why
- build a compact context pack with sources for the agent
- line up memory candidates for future sessions
Example prompts for the agent
- Check LINZA with
agent_workspace(action="doctor")and index the folder. - Show the first 3-5 review intents and explain your reasoning.
- Accept the material format "diagnostic logs" based on these examples.
How to install LINZA
Platform CLI
claude mcp add --env LINZA_VAULT=<LINZA_VAULT> --env LINZA_EMBED_PROVIDER=<LINZA_EMBED_PROVIDER> --env LINZA_EMBED_URL=<LINZA_EMBED_URL> --env LINZA_EMBED_MODEL=<LINZA_EMBED_MODEL> --env LINZA_EMBED_KEY=<LINZA_EMBED_KEY> --transport stdio linza -- uvx linza-mcpReplace <…> with your own values. 4 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from linza-mcp <command>
Platform CLI
codex mcp add linza --env LINZA_VAULT=<LINZA_VAULT> --env LINZA_EMBED_PROVIDER=<LINZA_EMBED_PROVIDER> --env LINZA_EMBED_URL=<LINZA_EMBED_URL> --env LINZA_EMBED_MODEL=<LINZA_EMBED_MODEL> --env LINZA_EMBED_KEY=<LINZA_EMBED_KEY> -- uvx linza-mcpReplace <…> with your own values. 4 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from linza-mcp <command>
Config file
{
"mcpServers": {
"linza": {
"command": "uvx",
"args": [
"linza-mcp"
],
"env": {
"LINZA_VAULT": "<LINZA_VAULT>",
"LINZA_EMBED_PROVIDER": "<LINZA_EMBED_PROVIDER>",
"LINZA_EMBED_URL": "<LINZA_EMBED_URL>",
"LINZA_EMBED_MODEL": "<LINZA_EMBED_MODEL>",
"LINZA_EMBED_KEY": "<LINZA_EMBED_KEY>"
}
}
}
}Replace <…> with your own values. 4 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from linza-mcp <command>
Config file
{
"servers": {
"linza": {
"type": "stdio",
"command": "uvx",
"args": [
"linza-mcp"
],
"env": {
"LINZA_VAULT": "<LINZA_VAULT>",
"LINZA_EMBED_PROVIDER": "<LINZA_EMBED_PROVIDER>",
"LINZA_EMBED_URL": "<LINZA_EMBED_URL>",
"LINZA_EMBED_MODEL": "<LINZA_EMBED_MODEL>",
"LINZA_EMBED_KEY": "<LINZA_EMBED_KEY>"
}
}
}
}Replace <…> with your own values. 4 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from linza-mcp <command>
Platform CLI
gemini mcp add -e LINZA_VAULT=<LINZA_VAULT> -e LINZA_EMBED_PROVIDER=<LINZA_EMBED_PROVIDER> -e LINZA_EMBED_URL=<LINZA_EMBED_URL> -e LINZA_EMBED_MODEL=<LINZA_EMBED_MODEL> -e LINZA_EMBED_KEY=<LINZA_EMBED_KEY> linza uvx linza-mcpReplace <…> with your own values. 4 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from linza-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about LINZA
How do I install LINZA in Claude Code?
Install the package first: python -m pip install linza-mcp. Then register the server with claude mcp add linza-mcp -e LINZA_EMBED_KEY=<LINZA_EMBED_KEY> -- uvx linza-mcp.
What does LINZA do?
It indexes a Markdown folder, keeps a local database at .linza/linza.db, and gives the agent a map of topics, material formats and links. Nothing is written until you review and confirm it.
Does LINZA need an embedding server?
The server starts and lists its tools without one, but semantic search, the topic map and link suggestions stay inactive. LM Studio with an embedding model is the simple local route.
