Examples

• Knowledge creation: A small Zettelkasten knowledge network about the Zettelkasten method itself

Note Types

The Zettelkasten MCP server supports different types of notes:

|Type|Handle|Description| |---|---|---| |Fleeting notes|fleeting|Quick, temporary notes for capturing ideas| |Literature notes|literature|Notes from reading material| |Permanent notes|permanent|Well-formulated, evergreen notes| |Structure notes|structure|Index or outline notes that organize other notes| |Hub notes|hub|Entry points to the Zettelkasten on key topics|

Link Types

The Zettelkasten MCP server uses a comprehensive semantic linking system that creates meaningful connections between notes. Each link type represents a specific relationship, allowing for a rich, multi-dimensional knowledge graph.

| Primary Link Type | Inverse Link Type | Relationship Description | |-------------------|-------------------|--------------------------| | reference | reference | Simple reference to related information (symmetric relationship) | | extends | extended_by | One note builds upon or develops concepts from another | | refines | refined_by | One note clarifies or improves upon another | | contradicts | contradicted_by | One note presents opposing views to another | | questions | questioned_by | One note poses questions about another | | supports | supported_by | One note provides evidence for another | | related | related | Generic relationship (symmetric relationship) |

Prompting

To ensure maximum effectiveness, we recommend using a system prompt ("project instructions"), project knowledge, and an appropriate chat prompt when asking the LLM to process information, or explore or synthesize your Zettelkasten notes. The docs directory in this repository contains the necessary files to get you started:

System prompts

Pick one:

• system-prompt.md
• system-prompt-with-protocol.md

Project knowledge

For end users:

• zettelkasten-methodology-technical.md
• link-types-in-zettelkasten-mcp-server.md
• (more info relevant to your project)

Chat Prompts

• chat-prompt-knowledge-creation.md
• chat-prompt-knowledge-creation-batch.md
• chat-prompt-knowledge-exploration.md
• chat-prompt-knowledge-synthesis.md

Project knowledge (dev)

For developers and contributors:

• Example - A simple MCP server.md
• MCP Python SDK-README.md
• llms-full.txt

NB: Optionally include the source code with a tool like repomix.

Storage Architecture

This system uses a dual storage approach:

1. Markdown Files: All notes are stored as human-readable Markdown files with YAML frontmatter for metadata. These files are the source of truth and can be:

   • Edited directly in any text editor
   • Placed under version control (Git, etc.)
   • Backed up using standard file backup procedures
   • Shared or transferred like any other text files

2. SQLite Database: Functions as an indexing layer that:

   • Facilitates efficient querying and search operations
   • Enables Claude to quickly traverse the knowledge graph
   • Maintains relationship information for faster link traversal
   • Is automatically rebuilt from Markdown files when needed

If you edit Markdown files directly outside the system, you'll need to run the zk_rebuild_index tool to update the database. The database itself can be deleted at any time - it will be regenerated from your Markdown files.

Installation

# Clone the repository
git clone https://github.com/entanglr/zettelkasten-mcp.git
cd zettelkasten-mcp

# Create a virtual environment with uv
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv add "mcp[cli]"

# Install dev dependencies
uv sync --all-extras

Configuration

Create a .env file in the project root by copying the example:

cp .env.example .env

Then edit the file to configure your connection parameters.

Usage

Starting the Server

python -m zettelkasten_mcp.main

Or with explicit configuration:

python -m zettelkasten_mcp.main --notes-dir ./data/notes --database-path ./data/db/zettelkasten.db

Connecting to Claude Desktop

Add the following configuration to your Claude Desktop:

{
  "mcpServers": {
    "zettelkasten": {
      "command": "/absolute/path/to/zettelkasten-mcp/.venv/bin/python",
      "args": [
        "-m",
        "zettelkasten_mcp.main"
      ],
      "env": {
        "ZETTELKASTEN_NOTES_DIR": "/absolute/path/to/zettelkasten-mcp/data/notes",
        "ZETTELKASTEN_DATABASE_PATH": "/absolute/path/to/zettelkasten-mcp/data/db/zettelkasten.db",
        "ZETTELKASTEN_LOG_LEVEL": "INFO"
      }
    }
  }
}

Available MCP Tools

All tools have been prefixed with zk_ for better organization:

| Tool | Description | |---|---| | zk_create_note | Create a new note with a title, content, and optional tags | | zk_get_note | Retrieve a specific note by ID or title | | zk_update_note | Update an existing note's content or metadata | | zk_delete_note | Delete a note | | zk_create_link | Create links between notes | | zk_remove_link | Remove links between notes | | zk_search_notes | Search for notes by content, tags, or links | | zk_get_linked_notes | Find notes linked to a specific note | | zk_get_all_tags | List all tags in the system | | zk_find_similar_notes | Find notes similar to a given note | | zk_find_central_notes | Find notes with the most connections | | zk_find_orphaned_notes | Find notes with no connections | | zk_list_notes_by_date | List notes by creation/update date | | zk_rebuild_index | Rebuild the database index from Markdown files |

Project Structure

zettelkasten-mcp/
├── src/
│   └── zettelkasten_mcp/
│       ├── models/       # Data models
│       ├── storage/      # Storage layer
│       ├── services/     # Business logic
│       └── server/       # MCP server implementation
├── data/
│   ├── notes/            # Note storage (Markdown files)
│   └── db/               # Database for indexing
├── tests/                # Test suite
├── .env.example          # Environment variable template
└── README.md

Tests

Comprehensive test suite for Zettelkasten MCP covering all layers of the application from models to the MCP server implementation.

How to Run the Tests

From the project root directory, run:

Using pytest directly

python -m pytest -v tests/

Using UV

uv run pytest -v tests/

With coverage report

uv run pytest --cov=zettelkasten_mcp --cov-report