zk-mcp

zk-mcp

zk-mcp 是一个 MCP（Model Context Protocol）服务，用于将由 zk 管理的笔记与大模型集成。 它支持大模型高效访问和使用由 zk 管理的知识库。

功能

• 笔记查询：按内容、标签和复杂筛选条件搜索笔记
• 链接分析：发现笔记之间的关系（链接到、被链接、相关）
• 标签管理：列出并按可用标签筛选
• 笔记访问：读取完整的笔记内容
• 创建笔记：以编程方式创建新笔记

前提条件

• 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 - 在开发模式下运行 MCP 服务，并设置 ZK_DIR=.
• 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 授权，详情请参阅 LICENSE 文件。