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:

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

2. Install dependencies:

uv sync

Configuration

Add the following settings to your MCP client's `servers.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.