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
Add this skill
npx mdskills install entanglr/zettelkasten-mcpComprehensive knowledge management MCP server with rich semantic linking and excellent documentation
1# Zettelkasten MCP Server23A 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.45## What is Zettelkasten?67The 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:891. **Atomicity**: Each note contains exactly one idea, making it a discrete unit of knowledge102. **Connectivity**: Notes are linked together to create a network of knowledge, with meaningful relationships between ideas113. **Emergence**: As the network grows, new patterns and insights emerge that weren't obvious when the individual notes were created1213What makes the Zettelkasten approach powerful is how it enables exploration in multiple ways:1415- **Vertical exploration**: dive deeper into specific topics by following connections within a subject area.16- **Horizontal exploration**: discover unexpected relationships between different fields by traversing links that cross domains.1718This 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.1920## Features2122- Create atomic notes with unique timestamp-based IDs23- Link notes bidirectionally to build a knowledge graph24- Tag notes for categorical organization25- Search notes by content, tags, or links26- Use markdown format for human readability and editing27- Integrate with Claude through MCP for AI-assisted knowledge management28- Dual storage architecture (see below)29- Synchronous operation model for simplified architecture3031## Examples3233- Knowledge creation: [A small Zettelkasten knowledge network about the Zettelkasten method itself](https://github.com/entanglr/zettelkasten-mcp/discussions/5)3435## Note Types3637The Zettelkasten MCP server supports different types of notes:3839|Type|Handle|Description|40|---|---|---|41|**Fleeting notes**|`fleeting`|Quick, temporary notes for capturing ideas|42|**Literature notes**|`literature`|Notes from reading material|43|**Permanent notes**|`permanent`|Well-formulated, evergreen notes|44|**Structure notes**|`structure`|Index or outline notes that organize other notes|45|**Hub notes**|`hub`|Entry points to the Zettelkasten on key topics|4647## Link Types4849The 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.5051| Primary Link Type | Inverse Link Type | Relationship Description |52|-------------------|-------------------|--------------------------|53| `reference` | `reference` | Simple reference to related information (symmetric relationship) |54| `extends` | `extended_by` | One note builds upon or develops concepts from another |55| `refines` | `refined_by` | One note clarifies or improves upon another |56| `contradicts` | `contradicted_by` | One note presents opposing views to another |57| `questions` | `questioned_by` | One note poses questions about another |58| `supports` | `supported_by` | One note provides evidence for another |59| `related` | `related` | Generic relationship (symmetric relationship) |6061## Prompting6263To 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:6465### System prompts6667Pick one:6869- [system-prompt.md](https://github.com/entanglr/zettelkasten-mcp/blob/main/docs/prompts/system/system-prompt.md)70- [system-prompt-with-protocol.md](https://github.com/entanglr/zettelkasten-mcp/blob/main/docs/prompts/system/system-prompt-with-protocol.md)7172### Project knowledge7374For end users:7576- [zettelkasten-methodology-technical.md](https://github.com/entanglr/zettelkasten-mcp/blob/main/docs/project-knowledge/user/zettelkasten-methodology-technical.md)77- [link-types-in-zettelkasten-mcp-server.md](https://github.com/entanglr/zettelkasten-mcp/blob/main/docs/project-knowledge/user/link-types-in-zettelkasten-mcp-server.md)78- (more info relevant to your project)7980### Chat Prompts8182- [chat-prompt-knowledge-creation.md](https://github.com/entanglr/zettelkasten-mcp/blob/main/docs/prompts/chat/chat-prompt-knowledge-creation.md)83- [chat-prompt-knowledge-creation-batch.md](https://github.com/entanglr/zettelkasten-mcp/blob/main/docs/prompts/chat/chat-prompt-knowledge-creation-batch.md)84- [chat-prompt-knowledge-exploration.md](https://github.com/entanglr/zettelkasten-mcp/blob/main/docs/prompts/chat/chat-prompt-knowledge-exploration.md)85- [chat-prompt-knowledge-synthesis.md](https://github.com/entanglr/zettelkasten-mcp/blob/main/docs/prompts/chat/chat-prompt-knowledge-synthesis.md)8687### Project knowledge (dev)8889For developers and contributors:9091- [Example - A simple MCP server.md](https://github.com/entanglr/zettelkasten-mcp/blob/main/docs/project-knowledge/dev/Example%20-%20A%20simple%20MCP%20server%20that%20exposes%20a%20website%20fetching%20tool.md)92- [MCP Python SDK-README.md](https://github.com/entanglr/zettelkasten-mcp/blob/main/docs/project-knowledge/dev/MCP%20Python%20SDK-README.md)93- [llms-full.txt](https://github.com/entanglr/zettelkasten-mcp/blob/main/docs/project-knowledge/dev/llms-full.txt)9495NB: Optionally include the source code with a tool like [repomix](https://github.com/yamadashy/repomix).9697## Storage Architecture9899This system uses a dual storage approach:1001011. **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:102 - Edited directly in any text editor103 - Placed under version control (Git, etc.)104 - Backed up using standard file backup procedures105 - Shared or transferred like any other text files1061072. **SQLite Database**: Functions as an indexing layer that:108 - Facilitates efficient querying and search operations109 - Enables Claude to quickly traverse the knowledge graph110 - Maintains relationship information for faster link traversal111 - Is automatically rebuilt from Markdown files when needed112113If 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.114115## Installation116117```bash118# Clone the repository119git clone https://github.com/entanglr/zettelkasten-mcp.git120cd zettelkasten-mcp121122# Create a virtual environment with uv123uv venv124source .venv/bin/activate # On Windows: .venv\Scripts\activate125126# Install dependencies127uv add "mcp[cli]"128129# Install dev dependencies130uv sync --all-extras131```132133## Configuration134135Create a `.env` file in the project root by copying the example:136137```bash138cp .env.example .env139```140141Then edit the file to configure your connection parameters.142143## Usage144145### Starting the Server146147```bash148python -m zettelkasten_mcp.main149```150151Or with explicit configuration:152153```bash154python -m zettelkasten_mcp.main --notes-dir ./data/notes --database-path ./data/db/zettelkasten.db155```156157### Connecting to Claude Desktop158159Add the following configuration to your Claude Desktop:160161```json162{163 "mcpServers": {164 "zettelkasten": {165 "command": "/absolute/path/to/zettelkasten-mcp/.venv/bin/python",166 "args": [167 "-m",168 "zettelkasten_mcp.main"169 ],170 "env": {171 "ZETTELKASTEN_NOTES_DIR": "/absolute/path/to/zettelkasten-mcp/data/notes",172 "ZETTELKASTEN_DATABASE_PATH": "/absolute/path/to/zettelkasten-mcp/data/db/zettelkasten.db",173 "ZETTELKASTEN_LOG_LEVEL": "INFO"174 }175 }176 }177}178```179180## Available MCP Tools181182All tools have been prefixed with `zk_` for better organization:183184| Tool | Description |185|---|---|186| `zk_create_note` | Create a new note with a title, content, and optional tags |187| `zk_get_note` | Retrieve a specific note by ID or title |188| `zk_update_note` | Update an existing note's content or metadata |189| `zk_delete_note` | Delete a note |190| `zk_create_link` | Create links between notes |191| `zk_remove_link` | Remove links between notes |192| `zk_search_notes` | Search for notes by content, tags, or links |193| `zk_get_linked_notes` | Find notes linked to a specific note |194| `zk_get_all_tags` | List all tags in the system |195| `zk_find_similar_notes` | Find notes similar to a given note |196| `zk_find_central_notes` | Find notes with the most connections |197| `zk_find_orphaned_notes` | Find notes with no connections |198| `zk_list_notes_by_date` | List notes by creation/update date |199| `zk_rebuild_index` | Rebuild the database index from Markdown files |200201## Project Structure202203```204zettelkasten-mcp/205├── src/206│ └── zettelkasten_mcp/207│ ├── models/ # Data models208│ ├── storage/ # Storage layer209│ ├── services/ # Business logic210│ └── server/ # MCP server implementation211├── data/212│ ├── notes/ # Note storage (Markdown files)213│ └── db/ # Database for indexing214├── tests/ # Test suite215├── .env.example # Environment variable template216└── README.md217```218219## Tests220221Comprehensive test suite for Zettelkasten MCP covering all layers of the application from models to the MCP server implementation.222223### How to Run the Tests224225From the project root directory, run:226227#### Using pytest directly228```bash229python -m pytest -v tests/230```231232#### Using UV233```bash234uv run pytest -v tests/235```236237#### With coverage report238```bash239uv run pytest --cov=zettelkasten_mcp --cov-report=term-missing tests/240```241242#### Running a specific test file243```bash244uv run pytest -v tests/test_models.py245```246247#### Running a specific test class248```bash249uv run pytest -v tests/test_models.py::TestNoteModel250```251252#### Running a specific test function253```bash254uv run pytest -v tests/test_models.py::TestNoteModel::test_note_validation255```256257### Tests Directory Structure258259```260tests/261├── conftest.py - Common fixtures for all tests262├── test_integration.py - Integration tests for the entire system263├── test_mcp_server.py - Tests for MCP server tools264├── test_models.py - Tests for data models265├── test_note_repository.py - Tests for note repository266├── test_search_service.py - Tests for search service267├── test_semantic_links.py - Tests for semantic linking268└── test_zettel_service.py - Tests for zettel service269```270271## Important Notice272273**⚠️ 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.274275## Credit Where Credit's Due276277This 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.278279## License280281MIT License282
Full transparency — inspect the skill content before installing.