Zettelkasten MCP Server: AI Notes & CEQRC Workflows

Overview

The Zettelkasten MCP Server is a developer-focused backend that brings AI-assisted workflows to a Zettelkasten-style note system. It implements the Model Context Protocol (MCP) to expose note contexts to language models and developer tools, enabling atomic notes, intelligent linking, and full-text search across your knowledge base. The server is designed to be used via CLI, REST API, or a simple web UI so you can integrate note workflows into scripts, apps, or interactive sessions.

This server is useful for researchers, writers, and engineers who want programmatic access to a linked-notes system with AI-enhanced operations. Common tasks such as creating atomic notes, querying by semantic similarity, surfacing context for model prompts, and automating CEQRC workflows are exposed as composable operations. The result is a reproducible, searchable, and model-aware Zettelkasten that can be embedded in larger toolchains.

Features

• Atomic note management (create, edit, version)
• MCP-compatible context serving for LLM integrations
• Full-text and vector search across notes and attachments
• Intelligent linking and backlink discovery (Zettelkasten-style)
• CEQRC workflows (Create → Edit → Query → Relate → Cite) supported via API/CLI
• CLI, REST API, and web UI access patterns
• Export/import and basic metadata support (tags, types, timestamps)
• Extensible indexer (local or vector store integrations)
• Webhooks and event hooks for automation

Installation / Configuration

Clone the repository and run with Docker (recommended for quick start):

# clone
git clone https://github.com/joshylchen/zettelkasten.git
cd zettelkasten

# start with Docker Compose
docker compose up -d

Run the server with Docker directly:

docker run -d \
  -p 8080:8080 \
  -v /path/to/notes:/data \
  -e MCP_PORT=8080 \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  ghcr.io/joshylchen/zettelkasten:latest

Or run locally (if the project provides a runtime script):

# example: using Node/Python start script
cd zettelkasten
npm install        # or pip install -r requirements.txt
npm run start      # or python -m zettelkasten.server

Recommended environment variables (examples — check repo docs for exact names):

• OPENAI_API_KEY — enable LLM-based features and MCP model integrations
• DATA_DIR — path to notes storage (defaults to ./data)
• MCP_PORT — HTTP port for the MCP server (defaults to 8080)
• INDEXER_TYPE — “local” or “vector” (configures search backend)

After startup, the server usually exposes:

• Web UI: http://localhost:8080
• REST API (MCP endpoints): http://localhost:8080/api
• CLI: shipped as a binary or as npm/pip script (see project README)

Available Tools

• CLI: create, edit, link, search, and export notes from terminal
  • Example: create a new atomic note

    zk new --title "Note Title" --content "Short idea summary..."
    

• REST API / MCP endpoints: retrieve contextual slices, search, and manage notes
  • Example: get context for a note (curl)

    curl -sS \
      "http://localhost:8080/api/mcp/context?note_id=123" \
      -H "Authorization: Bearer $API_TOKEN"
    

• Web UI: visual browser for notes, backlinks, search and CEQRC flows
• Search engine: full-text and vector search API for semantic queries
• Export/import: JSON or Markdown-compatible dumps for backup and interoperability

Use Cases

1. Literature review with AI-summarized highlights

   • Ingest PDFs or notes into the Zettelkasten store, then run semantic search to surface related notes. Use MCP context slices to feed LLM prompts (e.g., “Summarize key claims across these notes”) and attach the summary as a new atomic note.

2. Research workflows (CEQRC)

   • Create an atomic note for an idea, Edit to refine, Query the index to find related work, Relate by creating explicit links, and Cite by attaching source metadata. Automate this loop with the CLI or API to keep a reproducible research trail.

3. Team knowledge base

   • Use the server behind a small web UI so multiple contributors can add and link notes. Webhooks can trigger notifications when new notes or relationships are created, or when search queries reveal gaps.

4. Code-level integration for apps

   • Use MCP endpoints to provide context windows to external LLMs (e.g., assistant features inside an editor). The MCP server will return compact, relevant context slices so prompts stay within model limits.

Quick Reference: Common API Endpoints

For more implementation details, examples, and advanced configuration, see the project repository: https://github.com/joshylchen/zettelkasten.