Zettelkasten MCP

Zettelkasten MCP

Build a networked knowledge base using Niklas Luhmann's Zettelkasten methodology, powered by the zettelkasten-mcp MCP server. Notes are stored as Markdown files with YAML frontmatter (source of truth) and indexed in SQLite for fast graph traversal.

Luhmann's Zettelkasten

Niklas Luhmann (1927–1998), German sociologist, authored over 70 books and 400 articles using a physical slip-box (Zettelkasten). His method is the foundation of this system.

Core insight: A knowledge system should be a communication partner, not an archive. You should be surprised by what you find. Connections made across domains create emergent insights that no top-down hierarchy could anticipate.

Luhmann's four principles:

"A Zettelkasten that has grown over years is able to confront its owner with considerations he did not foresee." — Luhmann

Further reading: references/luhmann.md

Installation

The zettelkasten-mcp server is distributed via GitHub.

Quick install via uvx

# SSH (recommended)
uvx --from "git+ssh://git@github.com/entanglr/zettelkasten-mcp" zettelkasten-mcp

# HTTPS with GitHub CLI token
uvx --from "git+https://$(gh auth token)@github.com/entanglr/zettelkasten-mcp" zettelkasten-mcp

Install as a pinned version

uvx --from "git+ssh://git@github.com/entanglr/zettelkasten-mcp@v1.3.0" zettelkasten-mcp

Full installation guide: references/installation.md

MCP Configuration (mcp.json)

Add this block to your mcp.json (or settings.json under "mcp"):

{
  "mcpServers": {
    "zettelkasten": {
      "command": "uvx",
      "args": [
        "--from",
        "git+ssh://git@github.com/entanglr/zettelkasten-mcp",
        "zettelkasten-mcp",
        "--notes-dir",
        "/path/to/your/notes",
        "--database-path",
        "/path/to/your/db/zettelkasten.db"
      ]
    }
  }
}

Required environment variables (alternative to CLI args):

The database is derived from Markdown files — delete it at any time and run zk_rebuild_index to regenerate.

Note Types

Note quality gate (permanent notes)

• Single coherent idea — atomic
• Written in own words — not copied
• Self-contained — understandable without the source
• Declarative title: "Active Recall Strengthens Memory" not "Learning Note"
• 3–7 relevant tags
• Linked to 2+ existing notes with specific link types
• Citation if derived from a source

MCP Tools Reference

CRUD

Search & Discovery

Graph / Linking

Maintenance

Link Types

Choose the most specific type. related is a last resort.

Always set bidirectional: true so both notes show the connection.

Add a description: "X supports Y because..." — future-you will thank you.

Core Workflows

1. Create and Link a Note

1. zk_search_notes(query="<concept>")          → avoid duplicates
2. zk_create_note(title, content, type, tags)  → atomic note
3. zk_find_similar_notes(note_id)              → find connection candidates
4. zk_create_link(source, target, type,        → link immediately; never orphan
                  description, bidirectional=true)

2. Capture Research

1. Read paper/article → create fleeting notes per key point (one idea each)
2. After session → upgrade each fleeting note to literature note with [@citekey]
3. After synthesis → create permanent note combining insights across sources
4. Add to relevant MOC (structure note)

3. Knowledge Discovery

zk_find_central_notes(limit=10)          # What are your core concepts?
zk_find_orphaned_notes()                 # What needs linking or deleting?
zk_get_linked_notes(note_id, "both")     # What constellation surrounds idea X?
zk_find_similar_notes(note_id, 0.3)      # What is semantically adjacent?

4. Weekly Maintenance

1. Process fleeting notes → promote to literature/permanent or delete
2. Run zk_find_orphaned_notes() → link or cull
3. Run zk_find_central_notes() → create structure notes for emerging clusters
4. Run zk_get_all_tags() → merge duplicates (ai, artificial-intelligence → pick one)

Tagging Strategy

Rules: 3–7 tags per note · use hyphens, not spaces · check zk_get_all_tags() before coining new tags.

Markdown Note Format

Notes are stored with YAML frontmatter — human-readable and version-control friendly:

---
id: 20251109T120530123456789
title: Active Recall Strengthens Long-Term Memory
type: permanent
tags: [memory, learning, spaced-repetition, cognitive-science]
created: 2025-11-09T12:05:30.123456
updated: 2025-11-09T12:05:30.123456
---

# Active Recall Strengthens Long-Term Memory

Retrieving information from memory (testing yourself) produces stronger
retention than re-reading the same material. Each retrieval act modifies
the memory trace, making future retrieval easier.

[@roediger2006]

## Links

- supports [[20251109T115500000000000]] Spaced repetition exploits this mechanism
- extends [[20251109T114000000000000]] Desirable difficulties framework

Note IDs are timestamp-based (YYYYMMDDTHHMMSSssssssccc). The server generates these automatically.

Quick Start

# 1. Install the server
uvx --from "git+ssh://git@github.com/entanglr/zettelkasten-mcp" zettelkasten-mcp \
  --notes-dir ~/notes/zettelkasten \
  --database-path ~/notes/db/zettelkasten.db

# 2. Verify connectivity (in chat with MCP enabled)
# "List my 5 most central notes"

# 3. Create your first permanent note
# "Create a permanent note titled 'X' with these key points: ..."

# 4. Find what connects to it
# "Find notes similar to <note_id> and suggest links"