Zettelkasten MCP Server

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.

What is Zettelkasten?

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:

Atomicity: Each note contains exactly one idea, making it a discrete unit of knowledge
Connectivity: Notes are linked together to create a network of knowledge, with meaningful relationships between ideas
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.

Features

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

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:

Project knowledge

For end users:

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

Chat Prompts

Project knowledge (dev)

For developers and contributors:

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

Storage Architecture

This system uses a dual storage approach:

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
Database Index: 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
- Uses SQLite by default; provide a SQLAlchemy URL via ZETTELKASTEN_DATABASE for PostgreSQL or other backends

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

Installing via Smithery

To install Zettelkasten MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install zettelkasten-mcp --client claude

Via uvx

uvx --from=git+https://github.com/entanglr/zettelkasten-mcp zettelkasten-mcp --notes-dir ./data/notes --database ./data/db/zettelkasten.db

Local Development

# 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.

To use PostgreSQL instead of the bundled SQLite database, install the optional driver and point ZETTELKASTEN_DATABASE at a SQLAlchemy URL:

pip install "zettelkasten-mcp[postgresql]"
export ZETTELKASTEN_DATABASE="postgresql+psycopg://user:password@localhost:5432/zettelkasten"

Using pipx:

pipx install "zettelkasten-mcp[postgresql]"
export ZETTELKASTEN_DATABASE="postgresql+psycopg://user:password@localhost:5432/zettelkasten"

ZETTELKASTEN_DATABASE accepts either a filesystem path (default ./data/db/zettelkasten.db) or any SQLAlchemy-compatible URL. Legacy ZETTELKASTEN_DATABASE_PATH / ZETTELKASTEN_DATABASE_URL variables are still honored for backward compatibility.

For MySQL or MariaDB support, install the mysql extra and supply a URL using the pymysql driver:

pip install "zettelkasten-mcp[mysql]"
export ZETTELKASTEN_DATABASE="mysql+pymysql://user:password@localhost:3306/zettelkasten"

Using pipx:

pipx install "zettelkasten-mcp[mysql]"
export ZETTELKASTEN_DATABASE="mysql+pymysql://user:password@localhost:3306/zettelkasten"

For Microsoft SQL Server, install the sqlserver extra and point to an ODBC connection string (requires the appropriate system ODBC driver, e.g. ODBC Driver 18 for SQL Server):

pip install "zettelkasten-mcp[sqlserver]"
export ZETTELKASTEN_DATABASE="mssql+pyodbc://user:password@server/database?driver=ODBC+Driver+18+for+SQL+Server"

Using pipx:

pipx install "zettelkasten-mcp[sqlserver]"
export ZETTELKASTEN_DATABASE="mssql+pyodbc://user:password@server/database?driver=ODBC+Driver+18+for+SQL+Server"

Usage

Starting the Server

python -m zettelkasten_mcp

Or with explicit configuration:

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

Or with PostgreSQL:

python -m zettelkasten_mcp --notes-dir ./data/notes \
  --database postgresql+psycopg://user:password@localhost:5432/zettelkasten

Connecting to Claude Desktop

Using smithery

npx -y @smithery/cli install zettelkasten-mcp --client claude

Manually

Add the following configuration to your Claude Desktop:

{
  "mcpServers": {
    "zettelkasten": {
      "command": "/absolute/path/to/zettelkasten-mcp/.venv/bin/python",
      "args": ["-m", "zettelkasten_mcp"],
      "env": {
        "ZETTELKASTEN_NOTES_DIR": "/absolute/path/to/zettelkasten-mcp/data/notes",
        "ZETTELKASTEN_DATABASE": "postgresql+psycopg://user:password@localhost:5432/zettelkasten",
        "ZETTELKASTEN_LOG_LEVEL": "INFO"
      }
    }
  }
}

Set ZETTELKASTEN_DATABASE to a filesystem path for SQLite or any SQLAlchemy URL (for example PostgreSQL) to choose the backend.

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=term-missing tests/

Running a specific test file

uv run pytest -v tests/test_models.py

Running a specific test class

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

Running a specific test function

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

Tests Directory Structure

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

Important Notice

⚠️ 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.

Credit Where Credit's Due

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.

License

MIT License

Pre-commit (code formatting)

To keep code style consistent, this project uses pre-commit with black and isort configured.

Install and enable the hooks locally:

pip install pre-commit
pre-commit install
pre-commit run --all-files

If you use a virtual environment, make sure the environment is activated before running pre-commit install so the hooks point to the correct Python interpreter.

Editor configuration (VS Code)

This project includes recommended settings for Visual Studio Code to enable automatic import completions and organize imports on save. The workspace settings are in .vscode/settings.json and recommended extensions in .vscode/extensions.json.

Recommended VS Code extensions:

ms-python.python — Python language support
ms-python.vscode-pylance — Pylance language server (provides auto-import completions)

Important settings (already configured):

python.analysis.autoImportCompletions: true — shows auto-import suggestions in completions
editor.codeActionsOnSave.source.organizeImports: true — runs import sorting on save
editor.formatOnSave: true with Black as the formatter

Activate the workspace settings by opening the project in VS Code; you may need to install the extensions and reload the window.

Zettelkasten MCP Server

What is Zettelkasten?

Atomicity: Each note contains exactly one idea, making it a discrete unit of knowledge
Connectivity: Notes are linked together to create a network of knowledge, with meaningful relationships between ideas
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.

Features

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

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

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

System prompts

Pick one:

Project knowledge

For end users:

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

Chat Prompts

Project knowledge (dev)

For developers and contributors:

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

Storage Architecture

This system uses a dual storage approach:

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
Database Index: 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
- Uses SQLite by default; provide a SQLAlchemy URL via ZETTELKASTEN_DATABASE for PostgreSQL or other backends

Installation

Installing via Smithery

To install Zettelkasten MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install zettelkasten-mcp --client claude

Via uvx

uvx --from=git+https://github.com/entanglr/zettelkasten-mcp zettelkasten-mcp --notes-dir ./data/notes --database ./data/db/zettelkasten.db

Local Development

# 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.

To use PostgreSQL instead of the bundled SQLite database, install the optional driver and point ZETTELKASTEN_DATABASE at a SQLAlchemy URL:

pip install "zettelkasten-mcp[postgresql]"
export ZETTELKASTEN_DATABASE="postgresql+psycopg://user:password@localhost:5432/zettelkasten"

Using pipx:

pipx install "zettelkasten-mcp[postgresql]"
export ZETTELKASTEN_DATABASE="postgresql+psycopg://user:password@localhost:5432/zettelkasten"

For MySQL or MariaDB support, install the mysql extra and supply a URL using the pymysql driver:

pip install "zettelkasten-mcp[mysql]"
export ZETTELKASTEN_DATABASE="mysql+pymysql://user:password@localhost:3306/zettelkasten"

Using pipx:

pipx install "zettelkasten-mcp[mysql]"
export ZETTELKASTEN_DATABASE="mysql+pymysql://user:password@localhost:3306/zettelkasten"

For Microsoft SQL Server, install the sqlserver extra and point to an ODBC connection string (requires the appropriate system ODBC driver, e.g. ODBC Driver 18 for SQL Server):

pip install "zettelkasten-mcp[sqlserver]"
export ZETTELKASTEN_DATABASE="mssql+pyodbc://user:password@server/database?driver=ODBC+Driver+18+for+SQL+Server"

Using pipx:

pipx install "zettelkasten-mcp[sqlserver]"
export ZETTELKASTEN_DATABASE="mssql+pyodbc://user:password@server/database?driver=ODBC+Driver+18+for+SQL+Server"

Usage

Starting the Server

python -m zettelkasten_mcp

Or with explicit configuration:

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

Or with PostgreSQL:

python -m zettelkasten_mcp --notes-dir ./data/notes \
  --database postgresql+psycopg://user:password@localhost:5432/zettelkasten

Connecting to Claude Desktop

Using smithery

npx -y @smithery/cli install zettelkasten-mcp --client claude

Manually

Add the following configuration to your Claude Desktop:

{
  "mcpServers": {
    "zettelkasten": {
      "command": "/absolute/path/to/zettelkasten-mcp/.venv/bin/python",
      "args": ["-m", "zettelkasten_mcp"],
      "env": {
        "ZETTELKASTEN_NOTES_DIR": "/absolute/path/to/zettelkasten-mcp/data/notes",
        "ZETTELKASTEN_DATABASE": "postgresql+psycopg://user:password@localhost:5432/zettelkasten",
        "ZETTELKASTEN_LOG_LEVEL": "INFO"
      }
    }
  }
}

Set ZETTELKASTEN_DATABASE to a filesystem path for SQLite or any SQLAlchemy URL (for example PostgreSQL) to choose the backend.

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=term-missing tests/

Running a specific test file

uv run pytest -v tests/test_models.py

Running a specific test class

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

Running a specific test function

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

Tests Directory Structure

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

Important Notice

Credit Where Credit's Due

License

MIT License

Pre-commit (code formatting)

To keep code style consistent, this project uses pre-commit with black and isort configured.

Install and enable the hooks locally:

pip install pre-commit
pre-commit install
pre-commit run --all-files

If you use a virtual environment, make sure the environment is activated before running pre-commit install so the hooks point to the correct Python interpreter.

Editor configuration (VS Code)

Recommended VS Code extensions:

ms-python.python — Python language support
ms-python.vscode-pylance — Pylance language server (provides auto-import completions)

Important settings (already configured):

python.analysis.autoImportCompletions: true — shows auto-import suggestions in completions
editor.codeActionsOnSave.source.organizeImports: true — runs import sorting on save
editor.formatOnSave: true with Black as the formatter

Activate the workspace settings by opening the project in VS Code; you may need to install the extensions and reload the window.