zk-mcp

zk-mcp

zk-mcp は、zk で管理されているノートを LLM と統合するための MCP（Model Context Protocol）サーバーです。 zk で管理されているナレッジベースに LLM が効率的にアクセスし、操作できるようにします。

機能

• ノート検索：コンテンツ、タグ、複雑なフィルターを使ってノートを検索します
• リンク分析：ノート間の関連（リンク先、リンク元、関連ノート）を見つけます
• タグ管理：利用可能なタグを一覧表示し、タグで絞り込みます
• ノートへのアクセス：ノートの内容全体を読み取ります
• ノート作成：プログラムから新しいノートを作成します

前提条件

• zk：プレーンテキストのノート作成アシスタント
• uv
• 任意の MCP クライアント（例：Claude Desktop、Continue など）

インストール

1. このリポジトリをクローンします：

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

2. 依存関係をインストールします：

uv sync

設定

MCP クライアントの 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/"
      }
    }
  }
}

重要：/path/to/zk-mcp/ をこのリポジトリの実際のパスに、/path/to/your/zk-note-directory/ を zk ノートディレクトリのパスに置き換えてください。

利用可能な MCP ツール

このサーバーは次の MCP ツールを提供します：

get_note_paths

さまざまな条件に基づいてノートを検索します：

• include_str：コンテンツまたはファイル名に特定の文字列を含むノートに絞り込みます
• include_str_operand：複数の文字列フィルターに適用する論理演算子（AND／OR）
• exclude_str：特定の文字列を含むノートを除外します
• include_tags：タグでノートを絞り込みます
• include_tags_operand：複数のタグフィルターに適用する論理演算子（AND／OR）
• exclude_tags：特定のタグが付いたノートを除外します

get_linking_notes

ノート間の関連を見つけます：

• link_to_notes：指定したノートがリンクしているノート
• linked_by_notes：指定したノートにリンクしているノート
• related_notes：指定したノートに関連するノート

get_tags

ノートリポジトリで利用可能なすべてのタグを一覧表示します。

get_note

パスを指定して、特定のノートの内容全体を読み取ります。

create_note

任意のディレクトリに、指定したタイトルで新しいノートを作成します。

開発

コマンド

• make run - ZK_DIR=. を指定して、開発モードで MCP サーバーを実行します
• make format - ruff を使ってコードを整形します（インポート＋フォーマット）
• make lint - ruff によるリントと mypy による型チェックを実行します
• make test - pytest ですべてのテストを実行します
• make pre-commit - format と lint の両方を実行します（コミット前に推奨）

パッケージ管理

• uv add <package> - 実行時依存関係を追加します
• uv add --dev <package> - 開発用依存関係を追加します
• uv run <command> - 仮想環境でコマンドを実行します

アーキテクチャ

このサーバーは次の要素を使って構築されています：

• FastMCP：MCP サーバーの実装
• Pydantic：データの検証とシリアル化
• zk CLI：zk ノートシステムとのバックエンド統合

すべてのツールは、型安全性と検証のために Pydantic モデルを使用して JSON レスポンスを返します。

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルをご覧ください。