使用说明

项目简介

MCP-PKM-Logseq 是一个 Model Context Protocol (MCP) 服务器的实现，它允许 LLM（大型语言模型）客户端访问和操作存储在 Logseq 个人知识管理系统中的信息。通过该服务器，LLM 可以检索个人笔记、待办事项，并根据预定义的指令与用户的 Logseq 知识库进行交互，从而实现更智能的个人知识助手应用。

主要功能点

资源访问: 提供 'logseq://guide' 资源，用于获取关于如何与 Logseq 知识库交互的初始指令，帮助 LLM 理解用户的知识组织方式和偏好。
个人笔记检索: 通过 'get_personal_notes' 工具，LLM 可以根据主题和日期范围检索 Logseq 中的个人笔记。支持按标签和全文搜索，并返回 Markdown 格式的结果，方便 LLM 理解和处理。
待办事项管理: 'get_todo_list' 工具允许 LLM 获取 Logseq 中的待办事项列表，可以根据完成状态和日期范围进行过滤，帮助 LLM 理解用户的任务管理情况。

安装步骤

安装 Python 环境: 确保你的系统已安装 Python 3.7 或更高版本。
安装依赖: 使用 'uv' 包管理器（或 'pip'）安装项目依赖。
```
uv sync
```
构建项目: 使用 'uv' 构建项目。
```
uv build
```
这将在 'dist/' 目录下生成 wheel 文件。

安装 wheel 文件: 使用 'uv' 安装生成的 wheel 文件。

uv pip install dist/*.whl

服务器配置

MCP 服务器需要配置 Logseq HTTP API 的访问信息。以下是在 MCP 客户端（如 Claude）中配置 MCP-PKM-Logseq 服务器的示例配置信息。

Claude Desktop 和 Cursor 配置 (JSON 格式)

在 Claude Desktop 或 Cursor 的配置文件 ('claude_desktop_config.json') 中，找到 '"mcpServers"' 部分，并添加以下配置：

"mcpServers": {
  "mcp-pkm-logseq": {
    "command": "uvx",
    "args": [
      "mcp-pkm-logseq"
    ],
    "env": {
      "LOGSEQ_API_TOKEN": "your-logseq-api-token",  // 替换为你的 Logseq API Token
      "LOGSEQ_URL": "http://localhost:12315"      // Logseq HTTP API 的 URL，默认 localhost:12315
    }
  }
}

配置参数说明:

'"mcp-pkm-logseq"': 服务器名称，在 Claude 客户端中用于标识该 MCP 服务器。
'"command": "uvx"': 启动服务器的命令，这里使用 'uvx' 执行已安装的 'mcp-pkm-logseq' 包。
'"args": ["mcp-pkm-logseq"]': 传递给 'uvx' 命令的参数，指定要运行的包名。
'"env"': 环境变量配置。
- '"LOGSEQ_API_TOKEN"': 必填。你的 Logseq HTTP API Token，需要在 Logseq 设置中启用 HTTP API Server 并设置 Token。
- '"LOGSEQ_URL"': 可选。Logseq HTTP API 的 URL。如果 Logseq HTTP API 运行在默认端口 (12315) 的本地主机，则无需修改。

Claude Code 配置 (命令行)

在 Claude Code 中，可以使用 'claude mcp add' 命令添加 MCP 服务器：

claude mcp add mcp-pkm-logseq uvx mcp-pkm-logseq

Logseq HTTP API Server 配置

启用 HTTP API Server: 打开 Logseq 应用，进入设置 (Settings) -> 高级 (Advanced)，启用 "开发者模式 (Developer mode)" 和 "HTTP API Server"。
设置 API Token: 在 HTTP API Server 设置中，设置你的 API Token。确保此 Token 与 MCP 服务器配置中的 'LOGSEQ_API_TOKEN' 环境变量一致。

基本使用方法

启动 Logseq 应用并启用 HTTP API Server。
启动 Claude 客户端 (Desktop, Cursor 或 Code)。Claude 客户端会自动连接到配置的 MCP 服务器。
在 Logseq 中创建 "MCP PKM Logseq" 页面: 该页面用于存放 LLM 助手理解你的知识库所需的指南信息，例如：
- 标签系统描述 (项目、领域、资源等标签的含义)
- 常用标签列表和主题
- 知识组织工作流
- 页面和块的命名约定
- 信息检索偏好
- 常用主题组合示例
- 个人知识管理方法的相关背景信息

当 LLM 需要理解用户的知识库时，会自动访问 'logseq://guide' 资源，获取 "MCP PKM Logseq" 页面的内容，从而更好地与用户的个人知识进行交互。LLM 还可以调用 'get_personal_notes' 和 'get_todo_list' 工具来检索特定信息。

关键词