技术文档摘要

Logseq API MCP 服务器

用于 Logseq API 集成的 Model Context Protocol 服务器，具有动态工具发现功能

目录

• 概述
• 特性
• 安装
• 配置
• 可用工具
• 工具详情与示例
• 使用示例
• 开发
• 添加新工具
• 测试
• CI/CD 管道
• 贡献
• 许可证

概述

Logseq API MCP 服务器提供了 Model Context Protocol 客户端与 Logseq 知识库之间的无缝集成。此服务器使 AI 助手和其他 MCP 客户端能够与您的 Logseq 笔记进行交互，提取教育内容，分析知识关系，并通过一系列专门的工具处理结构化信息。

🚀 关键创新：具备一个动态工具发现系统，该系统会自动检测、导入并注册添加到 src/tools/ 目录中的任何新工具——无需任何配置！

适用于：

• 📚 教育内容管理 - 提取并组织闪卡和学习材料
• 🎓 学习系统 - 构建基于 AI 的学习助手和间隔重复工具
• 🔍 知识库分析 - 发现笔记中的关系和模式
• 📊 内容发现 - 使用 AI 辅助导航复杂的知识图谱
• 🧠 学术研究 - 分析课程材料和学习资源

特性

🛠️ 核心工具（9个可用）

读操作

1. get_all_pages - 包含元数据的完整页面列表
2. get_page_blocks - 层次块结构分析
3. get_page_links - 页面关系和引用发现
4. get_block_content - 包含子块的详细块内容
5. get_all_page_content - 综合页面内容提取
6. get_linked_flashcards - 高级闪卡收集和分析

写操作

7. append_block_in_page - 带有定位选项的页面块追加
8. create_page - 创建带有属性和格式的新页面
9. edit_block - 编辑现有块的内容、属性和光标控制

🔄 动态工具发现

• 自动发现 - 自动从 src/tools/ 找到并导入工具
• 零配置 - 不需要手动导入或注册
• 即时集成 - 新工具立即可用
• CI 验证 - 自动测试确保所有工具正常工作

🎯 优化用于 AI/LLM 消费

• 干净的结构化输出 - 带有表情符号的层次格式
• 教育内容聚焦 - 专门的闪卡和学习材料提取
• 全面的元数据 - 块 ID、UUID、时间戳、属性和关系
• 智能内容组织 - 自动分类和摘要生成
• 语言无关 - 适用于任何 Logseq 知识库语言

安装

先决条件

• Python 3.11+ - 支持异步/等待的现代 Python
• uv - 快速的 Python 包管理和项目管理
• 启用了 API 的运行中的 Logseq 实例
• 用于身份验证的 Logseq API 令牌

快速设置

1. 克隆仓库

   git clone https://github.com/gustavo-meilus/logseq-api-mcp.git
   cd logseq-api-mcp
   

2. 使用 uv 安装

   uv sync
   

3. 配置环境

   cp .env.template .env
   # 使用您的 Logseq API 详细信息编辑 .env 文件
   

4. 启动服务器

   uv run mcp run src/server.py
   

配置

在项目根目录创建一个 .env 文件：

# Logseq API 配置
LOGSEQ_API_ENDPOINT=http://127.0.0.1:12315/api
LOGSEQ_API_TOKEN=your_api_token_here

获取您的 Logseq API 令牌

1. 打开 Logseq 应用程序
2. 转到 设置 → 功能 → 开发者模式
3. 启用 “HTTP APIs 服务器”
4. 复制显示的 API 令牌
5. 注意 API 端点（默认：http://127.0.0.1:12315/api）
6. 激活 API

可用工具

工具	描述	输出	最佳用途
get_all_pages	列出所有页面及其基本元数据	568 页（135 日记，433 正常）	导航，页面发现
get_page_blocks	层次块树结构	多级树带 ID 和 UUID	结构分析，导航
get_page_links	页面链接到目标页面	带有元数据的引用分析	关系发现
get_block_content	包含子块的详细块信息	块内容 + 立即子块	深度内容分析
get_all_page_content	完整页面内容 + 引用	完整内容带链接源	综合内容审查
get_linked_flashcards	页面及其链接页面的闪卡	2 页共 20 张闪卡	学习材料提取
append_block_in_page	带有定位选项的页面块追加	成功确认带详细信息	内容创作，组织
create_page	创建带有属性的新页面	页面创建确认	页面管理，结构
edit_block	全面控制现有块的编辑	编辑确认带更改	内容修改，更新

工具详情与示例

🗂️ get_all_pages

目的：获取知识库中所有页面的干净列表

输出格式：

📊 LOGSEQ 页面列表
📈 总页数：568
📅 日记页数：135
📄 正常页数：433

📄 正常页面：
📄 领域驱动设计（DDD）I | ID：3460 | UUID：682cfd19-7df6-46e0-a6f3-c09eca3b2530
📄 软件工程 MBA | ID：170 | UUID：682fa28c-a3cc-47f2-ae65-7b7db57e1d67

用例：

• 知识库探索
• 页面清单和组织
• 通过名称或元数据查找特定页面

---

🌳 get_page_blocks

目的：获取任意页面的层次块结构

示例输入："领域驱动设计（DDD）I"

输出特征：

• 带缩进级别的树结构
• 块 ID、UUID 和父子关系
• 属性提取和元数据
• 多级层次支持（最多 8+ 级）

样本输出：

🌳 页面块树结构
📄 页面：领域驱动设计（DDD）I (ID：3460)
📊 总块数：1

📋 类型:: #课程 课程:: [[软件工程 MBA]]
   📊 ID：3544 | UUID：682cfd19-2826-46b7-8222-0821b11abc60 | 级别：1
   👇 子块：7

  H1 # 闪卡 [标题：1]
     📊 ID：3552 | UUID：682cfd19-4c9c-40dd-8cb1-c2625315b8ae | 级别：2
     👇 子块：10

---

🔗 get_page_links

目的：查找所有链接到目标页面的页面

示例结果为 "领域驱动设计（DDD）I"：

🔗 页面链接分析
📄 目标页面：领域驱动设计（DDD）I
📊 找到 1 个链接到此页面的页面

📄 1. 领域驱动设计（DDD）II
   🔑 ID：3588 | UUID：682cfd19-3a24-4636-a5d5-c62ea57d352e
   📊 引用：1 | 日记：否
   ⚙️ 属性：相关：领域驱动设计（DDD）I

应用：

• 发现相关内容和交叉引用
• 构建知识地图和关系图
• 查找课程序列和学习路径

---

🔍 get_block_content

目的：获取特定块及其直接子块的详细信息

示例输入：UUID 682cfd19-3c3f-427c-a0be-c5a3a197ea20

输出：

🔍 主块
📌 块 ID：3465
🔑 UUID：682cfd19-3c3f-427c-a0be-c5a3a197ea20

📝 内容：
💡 闪卡
为什么 DDD 优先考虑开发者与领域专家的合作？#card
+ [ ] 因为领域专家仅负责批准技术基础设施。
+ [ ] 为了确保软件是基于对领域的深入理解构建的，减少歧义和错误。

👶 直接子块：
🔸 子块 1：
正确答案：为了确保软件是基于对领域的深入理解构建的，减少歧义和错误。

---

📖 get_all_page_content

目的：从页面中提取综合内容，包括属性、块和链接引用

关键特点：

• 完整的层次内容结构
• 属性提取和格式化
• 闪卡识别和提取
• 链接引用分析
• 教育内容优化

示例摘要：

📖 领域驱动设计（DDD）I
📊 1 块 | 1 链接源

📄 综合内容：
📄 页面属性 [3544]
   📋 课程：软件工程 MBA | 类型：课程 | 教授：Guilherme Bezerra de Lima

🎯 # 闪卡 [3552]
   💡 闪卡 [3465]
      ❓ Q：为什么 DDD 优先考虑开发者与领域专家的合作？

---

✏️ append_block_in_page

目的：以精确的定位控制向任意页面追加新的块

关键特点：

• 定位选项 - 在特定块之前插入，作为兄弟块，或在页面末尾
• 页面级别块 - 支持页面级别块的创建
• 内容灵活性 - 支持任何文本内容，包括 Markdown
• 即时反馈 - 带有定位信息的详细确认

示例用法：

# 基本块追加
await append_block_in_page("我的页面", "这里的新内容")

# 在特定块之前定位
await append_block_in_page("我的页面", "重要说明", before="block-uuid-123")

# 作为另一个块的兄弟块
await append_block_in_page("我的页面", "相关内容", sibling="block-uuid-456")

# 页面级别块
await append_block_in_page("我的页面", "页面属性", is_page_block=True)

输出示例：

✅ **块追加成功**
📄 页面：我的页面
📝 内容：这里的新内容
📍 定位：页面末尾
🔗 **下一步操作**：
• 检查您的 Logseq 图以查看新块
• 使用 get_page_blocks 验证块是否已添加
• 使用 get_block_content 获取新块的详细信息

---

📄 create_page

目的：创建带有自定义属性和格式的新页面

关键特点：

• 属性支持 - 添加自定义属性和元数据
• 格式选项 - 支持 Markdown 和 Org 格式
• 日记检测 - 自动日记页面识别
• 全面元数据 - 完整的页面实体信息

示例用法：

# 基本页面创建
await create_page("新页面")

# 带属性
properties = {"状态": "活跃", "优先级": "高"}
await create_page("项目页面", properties=properties)

# 带格式指定
await create_page("Org 页面", format="org")

# 完整页面，包含所有选项
await create_page("完整页面", properties=properties, format="markdown")

输出示例：

✅ **页面创建成功**
📄 页面：新页面
⚙️ 设置属性：2 项
📝 格式：markdown
🔗 **下一步操作**：
• 检查您的 Logseq 图以查看新页面
• 使用 get_all_pages 验证页面是否已创建
• 使用 get_page_blocks 开始添加内容

---

✏️ edit_block

目的：完全控制内容、属性和行为的现有块编辑

关键特点：

• 内容编辑 - 修改块内容并预览
• 属性管理 - 添加、更新或删除块属性
• 光标控制 - 将光标定位在特定位置
• 焦点管理 - 控制编辑后块的焦点

示例用法：

# 仅编辑内容
await edit_block("block-uuid-123", content="更新后的内容")

# 更新属性
properties = {"状态": "已完成", "优先级": "高"}
await edit_block("block-uuid-123", properties=properties)

# 设置光标位置和焦点
await edit_block("block-uuid-123", cursor_position=10, focus=True)

# 完整编辑，包含所有选项
await edit_block("block-uuid-123",
                content="新内容",
                properties=properties,
                cursor_position=5,
                focus=True)

输出示例：

✅ **块编辑成功**
🔑 块 UUID：block-uuid-123
📝 **更新后的内容**：

新内容

⚙️ **更新后的属性**：
• 状态：已完成
• 优先级：高
📍 光标定位在索引 5
🎯 焦点：启用
🔗 **下一步操作**：
• 检查您的 Logseq 图以查看更新后的块
• 使用 get_block_content 验证更改
• 继续编辑或添加更多内容

---

🧠 get_linked_flashcards

目的：从目标页面及其所有链接页面中全面提取闪卡

实际结果示例为 "领域驱动设计（DDD）I"：

🎯 链接闪卡分析
📄 目标页面：领域驱动设计（DDD）I
🔗 搜索了 2 页（目标 + 1 链接）
💡 总计找到 20 张闪卡

📚 领域驱动设计（DDD）I (10 张闪卡)
📚 领域驱动设计（DDD）II (10 张闪卡)

📊 摘要：
• 总闪卡数：20
• 总答案块数：0
• 包含闪卡的页面数：2
• 每张闪卡平均答案数：0.0

高级功能：

• 多选题支持
• 答案块提取和链接
• 跨页面闪卡发现
• 教育元数据保留
• 学习系统集成准备就绪

使用示例

添加到您的 Claude Desktop MCP 设置 (~/.claude/claude_desktop_config.json)：

{
  "mcpServers": {