Zettelkasten MCP Server

The Model Context Protocol (MCP) standardizes how LLM applications interact with external data and functionality:

• Server: The core interface (e.g., FastMCP) that manages connections, protocol compliance, and message routing.
• Resources: Similar to GET endpoints in REST; they provide read-only data to be loaded into the LLM's context (e.g., config://app).
• Tools: Similar to POST endpoints; they allow the LLM to execute code or perform actions that have side effects (e.g., calculate_bmi).
• Prompts: Reusable templates that define interaction patterns for the LLM (e.g., a review_code template).

The Zettelkasten system uses specific note types to manage the lifecycle of an idea. Use these types when creating notes to maintain organizational clarity:

• Fleeting notes: Temporary, unprocessed thoughts for quick capture.
• Literature notes: Extracted ideas from external reading material, including proper citations.
• Permanent notes: Well-formulated, standalone ideas written in your own words (the core of the system).
• Structure notes: Maps or indexes that organize groups of notes on a specific topic.
• Hub notes: Broad entry points into the Zettelkasten for major areas of interest.

The MCP protocol is built on three core primitives:

The system recognizes specific typologies for notes and connections to structure the knowledge graph:

Note Typologies

• Literature Notes: Extracted concepts from external sources.
• Permanent Notes: Processed, individual units of knowledge.
• Structure Notes: Topical indexes used to organize related notes.
• Hub Notes: Curated entry points into specific subject areas.

Link Types

• Sequential Links: Fixed paths or temporal sequences.
• Structural Links: Hierarchical relationships.
• Associative Links: Conceptual connections between ideas.

Technical Syntax

• Internal References: Uses a standardized syntax, typically [[note-id]].
• Metadata: Often utilizes YAML frontmatter for attribute frameworks and tagging.

To build a rich knowledge network, use specific semantic link types instead of generic connections. This helps define the relationship between ideas:

The system uses a dual storage approach to balance human readability with machine performance:

1. Markdown Files (Source of Truth): All notes are stored as Markdown files with YAML frontmatter. You can edit these directly in any text editor or manage them via Git.
2. SQLite Database (Indexing Layer): An index used for efficient querying, searching, and rapid knowledge graph traversal by the LLM.

Important: If you edit Markdown files directly outside of the MCP tools, you must run the zk_rebuild_index tool to synchronize the SQLite database with your files. The database can be safely deleted and will be regenerated from the Markdown files.

Use FastMCP to quickly build a server that exposes tools (functions that perform actions) and resources (data endpoints).

from mcp.server.fastmcp import FastMCP

# Create an MCP server
mcp = FastMCP("Demo")

# Add an addition tool
@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

# Add a dynamic greeting resource
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """Get a personalized greeting"""
    return f"Hello, {name}!"

To install the Zettelkasten MCP server, clone the repository and set up a virtual environment using uv.

# 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

You can start the server using either the default stdio transport or the sse (Server-Sent Events) transport. If using SSE, you must specify a port.

Transport Options

• stdio: The default transport method.
• sse: Requires the --transport sse flag and a --port flag.

# Using stdio transport (default)
uv run mcp-simple-tool

# Using SSE transport on custom port
uv run mcp-simple-tool --transport sse --port 8000

To add the Model Context Protocol (MCP) to your Python project, use one of the following methods:

Using uv (Recommended): Add mcp[cli] to your dependencies to include the command-line tools.

Using pip: Install the base package.

To run the standalone MCP development tools via uv, use uv run mcp.

# Using uv
uv add "mcp[cli]"
uv run mcp

# Using pip
pip install mcp