zettelkasten-mcp

A Model Context Protocol (MCP) server that implements the Zettelkasten knowledge management methodology, allowing you to create, link, explore and synthesize atomic notes through Claude and other MCP-compatible clients.

The Zettelkasten method is a knowledge management system developed by German sociologist Niklas Luhmann, who used it to produce over 70 books and hundreds of articles. It consists of three core principles:

1. Atomicity: Each note contains exactly one idea, making it a discrete unit of knowledge
2. Connectivity: Notes are linked together to create a network of knowledge, with meaningful relationships between ideas
3. Emergence: As the network grows, new patterns and insights emerge that weren't obvious when the individual notes were created

What makes the Zettelkasten approach powerful is how it enables exploration in multiple ways:

• Vertical exploration: dive deeper into specific topics by following connections within a subject area.
• Horizontal exploration: discover unexpected relationships between different fields by traversing links that cross domains.

This structure invites serendipitous discoveries as you follow trails of thought from note to note, all while keeping each piece of information easily accessible through its unique identifier. Luhmann called his system his "second brain" or "communication partner" - this digital implementation aims to provide similar benefits through modern technology.

• Create atomic notes with unique timestamp-based IDs
• Link notes bidirectionally to build a knowledge graph
• Tag notes for categorical organization
• Search notes by content, tags, or links
• Use markdown format for human readability and editing
• Integrate with Claude through MCP for AI-assisted knowledge management
• Dual storage architecture (see below)
• Synchronous operation model for simplified architecture

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

The Zettelkasten MCP server supports different types of notes:

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.

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:

Pick one:

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

For end users:

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

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

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.

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.

# 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

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.

python -m zettelkasten_mcp.main

Or with explicit configuration:

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

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"
      }
    }
  }
}

All tools have been prefixed with zk_ for better organization:

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

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

From the project root directory, run:

python -m pytest -v tests/

uv run pytest -v tests/

uv run pytest --cov=zettelkasten_mcp --cov-report=term-missing tests/

uv run pytest -v tests/test_models.py

uv run pytest -v tests/test_models.py::TestNoteModel

uv run pytest -v tests/test_models.py::TestNoteModel::test_note_validation

tests/
├── conftest.py - Common fixtures for all tests
├── test_integration.py - Integration tests for the entire system
├── test_mcp_server.py - Tests for MCP server tools
├── test_models.py - Tests for data models
├── test_note_repository.py - Tests for note repository
├── test_search_service.py - Tests for search service
├── test_semantic_links.py - Tests for semantic linking
└── test_zettel_service.py - Tests for zettel service

⚠️ USE AT YOUR OWN RISK: This software is experimental and provided as-is without warranty of any kind. While efforts have been made to ensure data integrity, it may contain bugs that could potentially lead to data loss or corruption. Always back up your notes regularly and use caution when testing with important information.

This MCP server was crafted with the assistance of Claude, who helped organize the atomic thoughts of this project into a coherent knowledge graph. Much like a good Zettelkasten system, Claude connected the dots between ideas that might otherwise have remained isolated. Unlike Luhmann's paper-based system, however, Claude didn't require 90,000 index cards to be effective.

MIT License