zk-utils

zk-utils is an MCP (Model Context Protocol) server for zk note management tools. It provides functionality for note search, creation, and link analysis by integrating with zk.

Prerequisites

• zk command line tool

Related MCP server: brain-mcp

Usage

Using uvx (Recommended)

Add the following to mcp configuration file:

{
  "mcpServers": {
    "zk-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/koei-kaji/zk-utils", "zk-utils-mcp"],
      "env": {
        "ZK_DIR": "/path/to/your/notes"
      }
    }
  }
}

Environment Variables

• ZK_DIR: Path to zk notes directory (required)

Using Docker

Initial Setup

If you are creating a zk notebook for the first time, initialize the note directory with zk init:

cd /path/to/your/zk-notes
docker run -it --rm -v $(pwd):/zk-notes -w /zk-notes koeikajidev/zk-utils-mcp zk init

MCP Configuration

Add the following to mcp configuration file:

{
  "mcpServers": {
    "zk-utils": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/absolute/path/to/your/zk-notes:/zk-notes:ro",
        "koeikajidev/zk-utils-mcp"
      ]
    }
  }
}

Note: Use absolute path for the zk-notes directory.

Available MCP Tools

• get_notes: Search and retrieve zk notes with filtering and pagination

• get_note_content: Retrieve the full content of a specific zk note

• get_link_to_notes: Get all notes that are linked FROM the specified note (outbound links)

• get_linked_by_notes: Get all notes that link TO the specified note (inbound links)

• get_related_notes: Find notes that could be good candidates for linking

• get_tags: Retrieve all available tags from the zk note collection

• create_note: Create a new zk note with the specified title and path

• get_last_modified_note: Retrieve the most recently modified note

• get_tagless_notes: Retrieve all notes that have no tags assigned

• get_random_note: Retrieve a randomly selected note from the zk collection

Index Freshness

zk-utils automatically runs zk index --quiet before operations that rely on zk's index. Notes changed outside an LSP-aware editor, such as by shell scripts, sync tools, or AI agents, are therefore reindexed before zk-utils queries them; no separate scheduled reindexing is required for zk-utils itself.