zk-mcp

An MCP (Model Context Protocol) server that exposes zk Zettelkasten notebooks to Claude Desktop and Claude Code via stdio transport.

Overview

zk-mcp bridges your zk knowledge base with Claude, enabling full-text search, note creation, tag management, and knowledge graph exploration — all through natural conversation.

Claude Desktop/Code  ←— stdio (JSON-RPC) —→  zk-mcp (Rust)
                                                  │
                                        ┌─────────┴─────────┐
                                        │                    │
                                   zk CLI              Direct FS I/O
                              (search/list/create)     (read/write notes)
                                        │
                                     SQLite (zk DB)

Prerequisites

• Rust toolchain (edition 2024)
• zk CLI installed and available in $PATH
• An existing zk notebook (initialized with zk init)

Installation

Build and install from source:

cargo install --path .

Or build without installing:

cargo build --release
# Binary at target/release/zk-mcp

Quick Start

1. Generate configuration files

Run init-claude in your project directory to generate .mcp.json and a CLAUDE.md template:

zk-mcp init-claude

2. Configure for Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "zk": {
      "command": "zk-mcp",
      "args": ["--notebook", "/path/to/your/notebook"]
    }
  }
}

3. Configure for Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "zk": {
      "command": "zk-mcp",
      "args": ["--notebook", "/path/to/your/notebook"]
    }
  }
}

Alternatively, set the notebook path via environment variable:

export ZK_NOTEBOOK_DIR=/path/to/your/notebook

Configuration

Config file: ~/.config/zk-mcp/config.toml

Section	Key	Default	Description
general	notebook_dir	~/notebook	Path to zk notebook
general	default_limit	20	Max search results
general	max_content_length	10000	Max characters returned per note
general	auto_backlinks	true	Auto-fetch backlinks on read
tags	similarity_threshold	0.85	Jaro-Winkler fuzzy match threshold
tags	max_hierarchy_depth	3	Max tag nesting depth
tags.aliases	—	—	Custom tag mappings (e.g., typescript = "ts")
health	stub_threshold_words	50	Min words for non-stub notes

Priority: CLI args > environment variables > config file > defaults.

MCP Tools

Tool	Description
search_notes	Full-text search with FTS syntax, tag and date filtering
read_note	Read note content with frontmatter and optional backlinks
list_notes	List notes with filters (path, tag, date, orphan status)
list_tags	List all tags with usage counts
get_recent_notes	Get notes from a time period (today, this week, etc.)
get_backlinks	Explore incoming and outgoing links for a note
create_note	Create a new note with automatic tag normalization
append_note	Append content to an existing note
notebook_health	Check for stubs, orphans, and tagless notes
tag_stats	Tag statistics with co-occurrence analysis
find_related_context	Find related notes by keyword with relevance scoring

MCP Prompts

Prompt	Description	Arguments
daily_review	Summarize today's notes and extract tasks	—
knowledge_lookup	Cross-topic knowledge search	topic
note_from_conversation	Structure current conversation as a note	—
weekly_retrospective	Weekly reflection and knowledge growth analysis	—
project_context	Load project-relevant knowledge	project_keywords

MCP Resources

Static resources:

URI	Description
zk://tags	All tags with usage counts
zk://recent	Recent notes (past week)
zk://recent/today	Today's journal entries
zk://health	Notebook health summary
zk://stats	Tag statistics summary

Resource templates:

URI	Description
zk://tags/{tag_name}	Notes with a specific tag
zk://note/{path}	Content of a specific note

Tag Pipeline

Notes created through create_note pass through a three-stage tag normalization pipeline:

1. Normalizer — Lowercases, converts spaces/underscores to hyphens, normalizes hierarchy separators
2. Alias Map — Resolves known variants (e.g., typescript → ts, golang → go), configurable in config.toml
3. Validator — Checks against existing tags using Jaro-Winkler similarity; flags close matches for review

Development

cargo build              # Debug build
cargo build --release    # Release build
cargo test               # Run all tests
cargo clippy             # Lint
cargo fmt                # Format

License

This project is licensed under the GNU General Public License v3.0, the same license as zk.