Logseq MCP Tools

Logseq MCP 工具

本项目提供一组模型上下文协议（MCP）工具，让 AI Agent 能够与本地 Logseq 实例交互。

安装

1. 确保已安装 Python 3.11+
2. 克隆此仓库
3. 安装依赖：

   pip install -e .
   

设置

1. 确保已在 Logseq 中启用 API。

   • 在 Logseq 中，前往 Settings > Advanced > Developer mode > Enable Developer mode
   • 然后，前往 Plugins > Turn on Logseq Developer Plugin
   • 还要在 Advanced 设置中设置 API 令牌
   • 重启 Logseq

2. 在 Cursor MCP 配置文件中配置 MCP 服务（通常位于 ~/.cursor/mcp.json）：

   {
     "mcpServers": {
       "logseq": {
         "command": "/opt/homebrew/bin/uvx",
         "args": ["logseq-mcp"],
         "env": {
           "LOGSEQ_API_URL": "http://localhost:12315",
           "LOGSEQ_TOKEN": "your-token-here"
         }
       }
     }
   }
   

或者

3. 使用以下命令配置 Claude Code，以使用 MCP 服务：

claude mcp add

• 选择范围
• 选择 Stdio
• LOGSEQ_API_URL=http://localhost:12315 LOGSEQ_TOKEN=your-token-here /opt/homebrew/bin/uvx logseq-mcp

在 Cursor 和 Claude 中使用

添加到 Cursor 的 MCP 工具

1. 按照上方“设置”部分中的说明配置 MCP 服务

2. 打开 Cursor 并前往 MCP 面板（侧边栏）

3. Logseq 工具应显示在可用工具列表中

在 Claude 中使用

在 Cursor 中使用 Claude 时，需要通过类似以下提示词告知它你可以使用 Logseq 工具：

“你可以使用 Logseq 工具与我的 Logseq 图谱交互。你可以使用 logseq.get_all_pages()、logseq.get_page(name)、logseq.create_page(name) 等函数。”

可用工具

所有工具均位于 logseq 命名空间下：

页面

• logseq.get_all_pages：获取 Logseq 图谱中的所有页面列表
• logseq.get_page：按名称获取指定页面
• logseq.create_page：创建新页面
• logseq.delete_page：删除页面及其所有块

块

• logseq.get_page_blocks：获取指定页面中的所有块
• logseq.get_block：按 ID 获取指定块
• logseq.create_block：在页面上创建新块
• logseq.insert_block：将块插入为另一个块的子块
• logseq.update_block：更新现有块
• logseq.move_block：将块移至其他位置
• logseq.remove_block：删除块及其所有子块
• logseq.search_blocks：搜索与查询匹配的块

使用 Logseq

日志页面

Logseq 中的日志页面具有特定格式和属性：

1. 创建或访问日志页面时，使用格式“mmm dth, yyyy”（例如，“Apr 4th, 2025”）
2. Logseq 会自动为日志页面设置正确的日期格式
3. Logseq 会自动为日志页面设置特殊属性：
   • journal?：true - 表示这是日志页面
   • journalDay：YYYYMMDD - 数字格式的日期（例如，2025 年 4 月 4 日对应 20250404）
4. 示例：await logseq.create_page("Apr 4th, 2025")

重要： 无需手动设置 journal? 或 journalDay 属性。只需使用正确的日期格式创建页面（例如，“Apr 4th, 2025”），Logseq 就会自动将其配置为日志页面并设置相应属性。

块结构与格式

Logseq 中的块有一些需要了解的重要特征：

1. 自动项目符号：所有块都会在 Logseq UI 中自动呈现为项目符号

2. 页面链接：使用双方括号创建链接：[[Page Name]]

3. 层级块：

   • 块结构数据包含层级信息：
     • parent：父块的 ID
     • level：缩进级别（顶层为 1，缩进块为 2 或更高）
     • left：左侧的块（通常是缩进块的父块）

4. 块内容：创建块时，可以包含文本格式：

   • 支持基本 Markdown（粗体、斜体等）
   • 块内的项目符号可能只得到有限支持
   • 支持多行内容，但可能受 Logseq 解析规则影响

5. 日志块：在日志页面中创建的块会继承特殊属性：

   • journal?：true
   • journalDay：YYYYMMDD - 与日志页面相同

**注意：**与日志页面一样，这些块属性由 Logseq 自动处理。在日志页面上创建块时，无需手动设置 journal? 或 journalDay 属性。

常见任务示例

使用 Cursor Agent： 在 Cursor 中配置 Logseq MCP 工具后，可以向 Agent 提供如下提示词：

• “创建一个名为‘会议记录’的新页面，并为今天的议程添加项目符号”
• “将今天的任务添加到我的日志页面，并创建一个‘任务’部分”
• “使用 [[Project Plan]] 更新今天的日志条目，并将其子元素设为‘已完成里程碑 1’”
• “在我的图谱中搜索有关‘python 项目’的块，并将它们整理到一个新页面上”

Agent 将使用相应的 Logseq 工具在你的图谱中执行这些操作。