zettelkasten-mcp
The Zettelkasten MCP server enables AI-assisted knowledge management using the Zettelkasten methodology, allowing you to create, organize, link, and explore atomic notes through Claude and other MCP clients.
Note Management: Create, retrieve, update, and delete notes with different types (fleeting, literature, permanent, structure, hub), titles, content, and tags.
Semantic Linking: Build rich, bidirectional connections between notes using relationship types like extends, refines, contradicts, questions, supports, references, and related.
Search & Discovery: Search notes by content, tags, or type; find similar notes using similarity metrics; discover central hub notes with most connections; identify orphaned notes with no links; list notes by creation or update date within specified ranges; view all available tags.
Knowledge Graph Exploration: Traverse relationships by getting linked notes in any direction (incoming, outgoing, or both) to analyze your knowledge network structure.
Dual Storage System: Maintains human-readable Markdown files with YAML frontmatter as source of truth while using a database index for efficient querying, enabling both direct file editing and AI-assisted management.
Database Flexibility: Supports multiple database backends including SQLite (default), PostgreSQL, MySQL, and MS SQL Server via SQLAlchemy URLs.
System Maintenance: Rebuild the database index from Markdown files when editing notes externally to maintain data integrity.
Supports placing Markdown notes under Git version control for tracking changes to the knowledge base
Stores all notes as human-readable Markdown files with YAML frontmatter for metadata, enabling direct editing in any text editor and version control
Uses SQLite database as an indexing layer for efficient querying, searching, and traversing the knowledge graph while maintaining relationship information
Uses YAML frontmatter in Markdown files to store and manage note metadata
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@zettelkasten-mcp create a fleeting note about the benefits of atomic thinking"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: Zettelkasten MCP Server
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 |
| Quick, temporary notes for capturing ideas |
Literature notes |
| Notes from reading material |
Permanent notes |
| Well-formulated, evergreen notes |
Structure notes |
| Index or outline notes that organize other notes |
Hub notes |
| 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 |
|
| Simple reference to related information (symmetric relationship) |
|
| One note builds upon or develops concepts from another |
|
| One note clarifies or improves upon another |
|
| One note presents opposing views to another |
|
| One note poses questions about another |
|
| One note provides evidence for another |
|
| 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:
(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_DATABASEfor 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 claudeVia uvx
uvx --from=git+https://github.com/entanglr/zettelkasten-mcp zettelkasten-mcp --notes-dir ./data/notes --database ./data/db/zettelkasten.dbVia pipx (native macOS/Linux/Windows)
Install from GitHub:
pipx install "git+https://github.com/entanglr/zettelkasten-mcp.git"If/when published on PyPI, install from PyPI instead:
pipx install zettelkasten-mcpRun the server:
zettelkasten-mcp --notes-dir ./data/notes --database ./data/db/zettelkasten.dbNative Apple Silicon (non-Docker)
On Apple Silicon Macs, prefer pipx/uvx for native darwin/arm64
execution. Docker images are Linux-only (linux/amd64, linux/arm64) and do
not provide a native darwin container target.
Docker image architecture support
The latest image tag is published as a multi-arch image manifest with:
linux/amd64linux/arm64
Backend support in the container image differs by architecture:
Backend |
|
|
SQLite | Supported | Supported |
PostgreSQL | Supported | Supported |
MySQL/MariaDB | Supported | Supported |
SQL Server | Supported | Not supported |
linux/arm64 images intentionally skip SQL Server ODBC driver installation
(msodbcsql18) because upstream driver packaging is currently amd64-focused in
this Docker build strategy.
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-extrasConfiguration
Create a .env file in the project root by copying the example:
cp .env.example .envThen 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"Note for container users: SQL Server support is available in the published
Docker image on linux/amd64 only. On linux/arm64, the container does not
include SQL Server ODBC drivers, so use SQLite/PostgreSQL/MySQL instead.
Usage
Starting the Server
python -m zettelkasten_mcpOr with explicit configuration:
python -m zettelkasten_mcp --notes-dir ./data/notes --database ./data/db/zettelkasten.dbOr with PostgreSQL:
python -m zettelkasten_mcp --notes-dir ./data/notes \
--database postgresql+psycopg://user:password@localhost:5432/zettelkastenConnecting to Claude Desktop
Using smithery
npx -y @smithery/cli install zettelkasten-mcp --client claudeManually
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 |
| Create a new note with a title, content, and optional tags |
| Retrieve a specific note by ID or title |
| Update an existing note's content or metadata |
| Delete a note |
| Create links between notes |
| Remove links between notes |
| Search for notes by content, tags, or links |
| Find notes linked to a specific note |
| List all tags in the system |
| Find notes similar to a given note |
| Find notes with the most connections |
| Find notes with no connections |
| List notes by creation/update date |
| 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.mdTests
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.pyRunning a specific test class
uv run pytest -v tests/test_models.py::TestNoteModelRunning a specific test function
uv run pytest -v tests/test_models.py::TestNoteModel::test_note_validationTests 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 serviceImportant 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-filesIf 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 supportms-python.vscode-pylance— Pylance language server (provides auto-import completions)
Important settings (already configured):
python.analysis.autoImportCompletions: true— shows auto-import suggestions in completionseditor.codeActionsOnSave.source.organizeImports: true— runs import sorting on saveeditor.formatOnSave: truewith 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.
Available Tools
14 toolszk_create_linkB
Create a link between two notes. Args: source_id: ID of the source note target_id: ID of the target note link_type: Type of link (reference, extends, refines, contradicts, questions, supports, related) description: Optional description of the link bidirectional: Whether to create a link in both directions
Inputs: source_id (required), target_id (required), bidirectional, description, +1 more.
zk_create_noteB
Create a new Zettelkasten note. Args: title: The title of the note content: The main content of the note note_type: Type of note (fleeting, literature, permanent, structure, hub) tags: Comma-separated list of tags (optional)
Inputs: content (required), title (required), note_type, tags.
zk_delete_noteC
Delete a note. Args: note_id: The ID of the note to delete
Inputs: note_id (required).
zk_find_central_notesA
Find notes with the most connections (incoming + outgoing links). Notes are ranked by their total number of connections, determining their centrality in the knowledge network. Due to database constraints, only one link of each type is counted between any pair of notes.
Args:
limit: Maximum number of results to return (default: 10)
Inputs: limit.
zk_find_orphaned_notesB
Find notes with no connections to other notes.
Inputs: no named parameters.
zk_find_similar_notesB
Find notes similar to a given note. Args: note_id: ID of the reference note threshold: Similarity threshold (0.0-1.0) limit: Maximum number of results to return
Inputs: note_id (required), limit, threshold.
zk_get_all_tagsB
Get all tags in the Zettelkasten.
Inputs: no named parameters.
zk_get_linked_notesC
Get notes linked to/from a note. Args: note_id: ID of the note direction: Direction of links (outgoing, incoming, both)
Inputs: note_id (required), direction.
zk_get_noteB
Retrieve a note by ID or title. Args: identifier: The ID or title of the note
Inputs: identifier (required).
zk_list_notes_by_dateB
List notes created or updated within a date range. Args: start_date: Start date in ISO format (YYYY-MM-DD) end_date: End date in ISO format (YYYY-MM-DD) use_updated: Whether to use updated_at instead of created_at limit: Maximum number of results to return
Inputs: end_date, limit, start_date, use_updated.
zk_rebuild_indexB
Rebuild the database index from files.
Inputs: no named parameters.
zk_remove_linkB
Remove a link between two notes. Args: source_id: ID of the source note target_id: ID of the target note bidirectional: Whether to remove the link in both directions
Inputs: source_id (required), target_id (required), bidirectional.
zk_search_notesB
Search for notes by text, tags, or type. Args: query: Text to search for in titles and content tags: Comma-separated list of tags to filter by note_type: Type of note to filter by limit: Maximum number of results to return
Inputs: limit, note_type, query, tags.
zk_update_noteC
Update an existing note. Args: note_id: The ID of the note to update title: New title (optional) content: New content (optional) note_type: New note type (optional) tags: New comma-separated list of tags (optional)
Inputs: note_id (required), content, note_type, tags, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool has a clearly distinct purpose with no ambiguity. For example, zk_create_note, zk_update_note, and zk_delete_note handle different CRUD operations, while zk_find_central_notes, zk_find_orphaned_notes, and zk_find_similar_notes target specific query types. The link management tools (zk_create_link, zk_remove_link) are separate from note operations, ensuring agents can easily differentiate between them.
All tools follow a consistent 'zk_verb_noun' pattern with snake_case throughout. The verbs are descriptive and aligned with their functions (e.g., create, delete, get, list, find, search, update, rebuild). This uniformity makes the tool set predictable and easy for agents to navigate without confusion.
With 14 tools, this server is well-scoped for managing a Zettelkasten system. It covers essential operations like note CRUD, link management, and various query types (e.g., search, similarity, centrality). Each tool serves a specific purpose without redundancy, making the count appropriate for the domain's complexity and typical use cases.
The tool set provides complete coverage for Zettelkasten workflows, including full CRUD for notes and links, comprehensive querying (by text, tags, date, similarity, centrality, orphaned status), and maintenance (rebuild_index). There are no obvious gaps; agents can create, retrieve, update, delete, and analyze notes and their relationships seamlessly, supporting the entire knowledge management lifecycle.
Related MCP Connectors
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
MCP-native notes and memory for ChatGPT, Claude, and other AI tools.
Notes and memory assistant: one Markdown vault that Claude, ChatGPT and any MCP client can share.
One memory for all your AI tools: Claude, ChatGPT, Cursor and any MCP client share the same notes.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables users to create, link, explore, and synthesize atomic notes using the Zettelkasten method through MCP-compatible clients like Claude.MIT
- FlicenseNot gradedqualityAmaintenanceEnables users to create, link, search, explore, and synthesize atomic notes through Claude and other MCP-compatible clients, using markdown files and a SQLite index.-
- FlicenseNot gradedqualityAmaintenanceEnables Claude and other MCP-compatible clients to create, link, search, explore, and synthesize atomic Markdown notes organized as a connected knowledge graph with tags and semantic relationships.-
- FlicenseNot gradedqualityAmaintenanceEnables Claude and other MCP-compatible clients to create, link, explore, and synthesize atomic notes with semantic relationships, tags, search, and a Markdown-backed knowledge graph.-