Skip to content
Back to search

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/entanglr--zettelkasten-mcp/badge.svg)](/listings/entanglr--zettelkasten-mcp)

HTML

<a href="/listings/entanglr--zettelkasten-mcp"><img src="/api/listings/entanglr--zettelkasten-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 281 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Zettelkasten MCP Server
  2. 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.
  3. ## What is Zettelkasten?
  4. 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:
  5. 1. **Atomicity**: Each note contains exactly one idea, making it a discrete unit of knowledge
  6. 2. **Connectivity**: Notes are linked together to create a network of knowledge, with meaningful relationships between ideas
  7. 3. **Emergence**: As the network grows, new patterns and insights emerge that weren't obvious when the individual notes were created
  8. What makes the Zettelkasten approach powerful is how it enables exploration in multiple ways:
  9. - **Vertical exploration**: dive deeper into specific topics by following connections within a subject area.
  10. - **Horizontal exploration**: discover unexpected relationships between different fields by traversing links that cross domains.
  11. 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.
  12. ## Features
  13. - Create atomic notes with unique timestamp-based IDs
  14. - Link notes bidirectionally to build a knowledge graph
  15. - Tag notes for categorical organization
  16. - Search notes by content, tags, or links
  17. - Use markdown format for human readability and editing
  18. - Integrate with Claude through MCP for AI-assisted knowledge management
  19. - Dual storage architecture (see below)
  20. - Synchronous operation model for simplified architecture
  21. ## Examples
  22. - Knowledge creation: [A small Zettelkasten knowledge network about the Zettelkasten method itself](https://github.com/entanglr/zettelkasten-mcp/discussions/5)
  23. ## Note Types
  24. The Zettelkasten MCP server supports different types of notes:
  25. |Type|Handle|Description|
  26. |---|---|---|
  27. |**Fleeting notes**|`fleeting`|Quick, temporary notes for capturing ideas|
  28. |**Literature notes**|`literature`|Notes from reading material|
  29. |**Permanent notes**|`permanent`|Well-formulated, evergreen notes|
  30. |**Structure notes**|`structure`|Index or outline notes that organize other notes|
  31. |**Hub notes**|`hub`|Entry points to the Zettelkasten on key topics|
  32. ## Link Types
  33. 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.
  34. | Primary Link Type | Inverse Link Type | Relationship Description |
  35. |-------------------|-------------------|--------------------------|
  36. | `reference` | `reference` | Simple reference to related information (symmetric relationship) |
  37. | `extends` | `extended_by` | One note builds upon or develops concepts from another |
  38. | `refines` | `refined_by` | One note clarifies or improves upon another |
  39. | `contradicts` | `contradicted_by` | One note presents opposing views to another |
  40. | `questions` | `questioned_by` | One note poses questions about another |
  41. | `supports` | `supported_by` | One note provides evidence for another |
  42. | `related` | `related` | Generic relationship (symmetric relationship) |
  43. ## Prompting
  44. 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:
  45. ### System prompts
  46. Pick one:
  47. - [system-prompt.md](https://github.com/entanglr/zettelkasten-mcp/blob/main/docs/prompts/system/system-prompt.md)
  48. - [system-prompt-with-protocol.md](https://github.com/entanglr/zettelkasten-mcp/blob/main/docs/prompts/system/system-prompt-with-protocol.md)
  49. ### Project knowledge
  50. For end users:
  51. - [zettelkasten-methodology-technical.md](https://github.com/entanglr/zettelkasten-mcp/blob/main/docs/project-knowledge/user/zettelkasten-methodology-technical.md)
  52. - [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)
  53. - (more info relevant to your project)
  54. ### Chat Prompts
  55. - [chat-prompt-knowledge-creation.md](https://github.com/entanglr/zettelkasten-mcp/blob/main/docs/prompts/chat/chat-prompt-knowledge-creation.md)
  56. - [chat-prompt-knowledge-creation-batch.md](https://github.com/entanglr/zettelkasten-mcp/blob/main/docs/prompts/chat/chat-prompt-knowledge-creation-batch.md)
  57. - [chat-prompt-knowledge-exploration.md](https://github.com/entanglr/zettelkasten-mcp/blob/main/docs/prompts/chat/chat-prompt-knowledge-exploration.md)
  58. - [chat-prompt-knowledge-synthesis.md](https://github.com/entanglr/zettelkasten-mcp/blob/main/docs/prompts/chat/chat-prompt-knowledge-synthesis.md)
  59. ### Project knowledge (dev)
  60. For developers and contributors:
  61. - [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)
  62. - [MCP Python SDK-README.md](https://github.com/entanglr/zettelkasten-mcp/blob/main/docs/project-knowledge/dev/MCP%20Python%20SDK-README.md)
  63. - [llms-full.txt](https://github.com/entanglr/zettelkasten-mcp/blob/main/docs/project-knowledge/dev/llms-full.txt)
  64. NB: Optionally include the source code with a tool like [repomix](https://github.com/yamadashy/repomix).
  65. ## Storage Architecture
  66. This system uses a dual storage approach:
  67. 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:
  68. - Edited directly in any text editor
  69. - Placed under version control (Git, etc.)
  70. - Backed up using standard file backup procedures
  71. - Shared or transferred like any other text files
  72. 2. **SQLite Database**: Functions as an indexing layer that:
  73. - Facilitates efficient querying and search operations
  74. - Enables Claude to quickly traverse the knowledge graph
  75. - Maintains relationship information for faster link traversal
  76. - Is automatically rebuilt from Markdown files when needed
  77. 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.
  78. ## Installation
  79. ```bash
  80. # Clone the repository
  81. git clone https://github.com/entanglr/zettelkasten-mcp.git
  82. cd zettelkasten-mcp
  83. # Create a virtual environment with uv
  84. uv venv
  85. source .venv/bin/activate # On Windows: .venv\Scripts\activate
  86. # Install dependencies
  87. uv add "mcp[cli]"
  88. # Install dev dependencies
  89. uv sync --all-extras
  90. ```
  91. ## Configuration
  92. Create a `.env` file in the project root by copying the example:
  93. ```bash
  94. cp .env.example .env
  95. ```
  96. Then edit the file to configure your connection parameters.
  97. ## Usage
  98. ### Starting the Server
  99. ```bash
  100. python -m zettelkasten_mcp.main
  101. ```
  102. Or with explicit configuration:
  103. ```bash
  104. python -m zettelkasten_mcp.main --notes-dir ./data/notes --database-path ./data/db/zettelkasten.db
  105. ```
  106. ### Connecting to Claude Desktop
  107. Add the following configuration to your Claude Desktop:
  108. ```json
  109. {
  110. "mcpServers": {
  111. "zettelkasten": {
  112. "command": "/absolute/path/to/zettelkasten-mcp/.venv/bin/python",
  113. "args": [
  114. "-m",
  115. "zettelkasten_mcp.main"
  116. ],
  117. "env": {
  118. "ZETTELKASTEN_NOTES_DIR": "/absolute/path/to/zettelkasten-mcp/data/notes",
  119. "ZETTELKASTEN_DATABASE_PATH": "/absolute/path/to/zettelkasten-mcp/data/db/zettelkasten.db",
  120. "ZETTELKASTEN_LOG_LEVEL": "INFO"
  121. }
  122. }
  123. }
  124. }
  125. ```
  126. ## Available MCP Tools
  127. All tools have been prefixed with `zk_` for better organization:
  128. | Tool | Description |
  129. |---|---|
  130. | `zk_create_note` | Create a new note with a title, content, and optional tags |
  131. | `zk_get_note` | Retrieve a specific note by ID or title |
  132. | `zk_update_note` | Update an existing note's content or metadata |
  133. | `zk_delete_note` | Delete a note |
  134. | `zk_create_link` | Create links between notes |
  135. | `zk_remove_link` | Remove links between notes |
  136. | `zk_search_notes` | Search for notes by content, tags, or links |
  137. | `zk_get_linked_notes` | Find notes linked to a specific note |
  138. | `zk_get_all_tags` | List all tags in the system |
  139. | `zk_find_similar_notes` | Find notes similar to a given note |
  140. | `zk_find_central_notes` | Find notes with the most connections |
  141. | `zk_find_orphaned_notes` | Find notes with no connections |
  142. | `zk_list_notes_by_date` | List notes by creation/update date |
  143. | `zk_rebuild_index` | Rebuild the database index from Markdown files |
  144. ## Project Structure
  145. ```
  146. zettelkasten-mcp/
  147. ├── src/
  148. │ └── zettelkasten_mcp/
  149. │ ├── models/ # Data models
  150. │ ├── storage/ # Storage layer
  151. │ ├── services/ # Business logic
  152. │ └── server/ # MCP server implementation
  153. ├── data/
  154. │ ├── notes/ # Note storage (Markdown files)
  155. │ └── db/ # Database for indexing
  156. ├── tests/ # Test suite
  157. ├── .env.example # Environment variable template
  158. └── README.md
  159. ```
  160. ## Tests
  161. Comprehensive test suite for Zettelkasten MCP covering all layers of the application from models to the MCP server implementation.
  162. ### How to Run the Tests
  163. From the project root directory, run:
  164. #### Using pytest directly
  165. ```bash
  166. python -m pytest -v tests/
  167. ```
  168. #### Using UV
  169. ```bash
  170. uv run pytest -v tests/
  171. ```
  172. #### With coverage report
  173. ```bash
  174. uv run pytest --cov=zettelkasten_mcp --cov-report=term-missing tests/
  175. ```
  176. #### Running a specific test file
  177. ```bash
  178. uv run pytest -v tests/test_models.py
  179. ```
  180. #### Running a specific test class
  181. ```bash
  182. uv run pytest -v tests/test_models.py::TestNoteModel
  183. ```
  184. #### Running a specific test function
  185. ```bash
  186. uv run pytest -v tests/test_models.py::TestNoteModel::test_note_validation
  187. ```
  188. ### Tests Directory Structure
  189. ```
  190. tests/
  191. ├── conftest.py - Common fixtures for all tests
  192. ├── test_integration.py - Integration tests for the entire system
  193. ├── test_mcp_server.py - Tests for MCP server tools
  194. ├── test_models.py - Tests for data models
  195. ├── test_note_repository.py - Tests for note repository
  196. ├── test_search_service.py - Tests for search service
  197. ├── test_semantic_links.py - Tests for semantic linking
  198. └── test_zettel_service.py - Tests for zettel service
  199. ```
  200. ## Important Notice
  201. **⚠️ 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.
  202. ## Credit Where Credit's Due
  203. 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.
  204. ## License
  205. MIT License

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.