Skip to content

README.md

Latest commit

 

History

History
169 lines (126 loc) · 5.32 KB

README.md

File metadata and controls

169 lines (126 loc) · 5.32 KB

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.