zk-mcp

zk-mcp is an MCP (Model Context Protocol) server for integrating notes managed by zk with LLMs.

It enables LLMs to efficiently access and interact with knowledge bases managed under zk.

Features

Note Query: Search notes by content, tags, and complex filters
Link Analysis: Discover relationships between notes (links to, linked by, related)
Tag Management: List and filter by available tags
Note Access: Read complete note contents
Note Creation: Create new notes programmatically

Prerequisites

zk : a plain text note-taking assistant
uv
Any MCP client (e.g., Claude Desktop, Continue, etc.)

Installation

1. Clone this repository:

bash

git clone https://github.com/koei-kaji/zk-mcp.git
cd zk-mcp

2. Install dependencies:

bash

uv sync

Configuration

Add the following settings to your MCP client's servers.json:

json

{
  "mcpServers": {
    "zk": {
      "alwaysAllow": [
        "get_note",
        "get_note_paths",
        "get_linking_notes",
        "get_tags",
        "create_note"
      ],
      "args": [
        "--directory",
        "/path/to/zk-mcp/",
        "run",
        "server.py"
      ],
      "command": "uv",
      "env": {
        "ZK_DIR": "/path/to/your/zk-note-directory/"
      }
    }
  }
}

Important: Replace /path/to/zk-mcp/ with the actual path to this repository and /path/to/your/zk-note-directory/ with the path to your zk notes directory.

Available MCP Tools

This server provides the following MCP tools:

`get_note_paths`

Search for notes based on various criteria:

include_str: Filter notes containing specific strings in content or filename
include_str_operand: Logical operator (AND/OR) for multiple string filters
exclude_str: Exclude notes containing specific strings
include_tags: Filter notes by tags
include_tags_operand: Logical operator (AND/OR) for multiple tag filters
exclude_tags: Exclude notes with specific tags

`get_linking_notes`

Discover note relationships:

link_to_notes: Notes that the specified note links to
linked_by_notes: Notes that link to the specified note
related_notes: Notes that are related to the specified note

`get_tags`

List all available tags in the note repository.

`get_note`

Read the complete content of a specific note by path.

`create_note`

Create a new note with the specified title in an optional directory.

Development

Commands

make run - Run the MCP server in development mode with ZK_DIR=.
make format - Format code using ruff (imports + formatting)
make lint - Run linting with ruff and type checking with mypy
make test - Run all tests with pytest
make pre-commit - Run both format and lint (recommended before commits)

Package Management

uv add - Add runtime dependency
uv add --dev - Add development dependency
uv run - Run command in virtual environment

Architecture

The server is built using:

FastMCP: MCP server implementation
Pydantic: Data validation and serialization
zk CLI: Backend integration with zk note system

All tools return JSON responses using Pydantic models for type safety and validation.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Zk Mcp

Documentation