MCP server for LogSeq

✨ 你可以做什么

将你的 LogSeq 知识库变成 AI 驱动的工作空间！此 MCP 服务让 Claude 能够无缝地与你的 LogSeq 图谱交互。

🎯 实际应用示例

📊 智能知识管理

"Analyze all my project notes from the past month and create a status summary"
"Find pages mentioning 'machine learning' and create a study roadmap"
"Search for incomplete tasks across all my pages"

📝 自动创建内容

"Create a new page called 'Today's Standup' with my meeting notes"
"Add today's progress update to my existing project timeline page"  
"Create a weekly review page from my recent notes"

🔍 智能研究与分析

"Compare my notes on React vs Vue and highlight key differences"
"Find all references to 'customer feedback' and summarize themes"
"Create a knowledge map connecting related topics across pages"

🧠 语义搜索 （可选，需要配置向量搜索）

"Find everything I wrote about burnout, even if I didn't use that word"
"What notes relate to my thoughts on deep work?"
"Search across my Dutch and English notes for ideas about productivity"

🤝 会议与文档工作流

"Read my meeting notes and create individual task pages for each action item"
"Get my journal entries from this week and create a summary page"
"Search for 'Q4 planning' and organize all related content into a new overview page"

💡 主要优势

• 无需切换上下文：Claude 可直接使用你的 LogSeq 数据
• 保留你的工作流：无需手动导出或复制内容
• 智能整理：AI 驱动的页面创建、链接和搜索
• 提升效率：自动处理重复性知识工作
• 语义向量搜索 （可选）：使用本地 Ollama 或托管的 OpenAI 兼容嵌入模型，按含义查找笔记
• DB 模式支持 （可选启用）：读取和写入 Logseq DB 模式图谱中的类属性

---

🚀 快速开始

步骤 1：启用 LogSeq API

1. 设置 → 功能 → 勾选“启用 HTTP API 服务器”
2. 点击 LogSeq 中的 API 按钮（🔌） → “启动服务器”
3. 生成 API 令牌：API 面板 → “授权令牌” → 创建新令牌

步骤 2：添加到你的 MCP 客户端（无需安装！）

Claude Code

claude mcp add mcp-logseq \
  --env LOGSEQ_API_TOKEN=your_token_here \
  --env LOGSEQ_API_URL=http://localhost:12315 \
  -- uv run --with mcp-logseq mcp-logseq

Claude Desktop

将以下内容添加到配置文件（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "mcp-logseq": {
      "command": "uv",
      "args": ["run", "--with", "mcp-logseq", "mcp-logseq"],
      "env": {
        "LOGSEQ_API_TOKEN": "your_token_here",
        "LOGSEQ_API_URL": "http://localhost:12315"
      }
    }
  }
}

Codex CLI

安装好 uv 并运行 Logseq 的 HTTP API（步骤 1）后，将以下内容添加到 ~/.codex/config.toml：

[mcp_servers.logseq]
command = "uv"
args = ["run", "--with", "mcp-logseq", "mcp-logseq"]

[mcp_servers.logseq.env]
LOGSEQ_API_TOKEN = "YOUR_LOGSEQ_TOKEN"
LOGSEQ_API_URL = "http://127.0.0.1:12315"

将 YOUR_LOGSEQ_TOKEN 替换为你的 Logseq 令牌。如果 Codex 找不到 uv，请在终端中运行 which uv，并在 command 中使用完整路径。请妥善保管你的令牌。

使用上面的 API 基地址，不要包含 /mcp。Codex 通过 STDIO 运行此适配器；适配器连接到 Logseq 的常规 HTTP API。

重启 Codex，打开新的本地任务，然后询问：

使用 Logseq 列出我的日志页面，然后读取今天的日志。不要进行任何更改。

请保持 Logseq 及其 API 服务器运行。Codex 会自动启动适配器，无需隧道或单独的终端窗口。

已使用 Logseq DB 图谱测试页面列表和日志检索。此配置适用于本地 Codex 任务，不适用于托管在云端的 ChatGPT Chat。

OpenCode

将以下内容添加到 ~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp-logseq": {
      "type": "local",
      "command": ["uv", "run", "--with", "mcp-logseq", "mcp-logseq"],
      "enabled": true,
      "environment": {
        "LOGSEQ_API_URL": "http://localhost:12315",
        "LOGSEQ_API_TOKEN": "your_token_here"
      }
    }
  }
}

步骤 3：开始使用！

"Please help me organize my LogSeq notes. Show me what pages I have."

---

🔬 向量搜索（可选）

使用可配置的嵌入模型对 Logseq 图谱进行语义搜索——按含义而非仅按关键词查找笔记。结合向量相似度和全文搜索，搜索所有页面，并支持跨语言搜索。

可使用 Ollama 在本地运行嵌入模型，也可使用 OpenAI 或其他 OpenAI 兼容的嵌入接口。LanceDB 在所有配置中都在本地运行。托管服务提供商会收到用于生成嵌入的笔记文本。

→ 完整配置指南：VECTOR_SEARCH.md

---

🛠️ 可用工具

该服务提供 17 种工具，支持智能 Markdown 解析；另有 3 种可选的向量搜索工具：

工具	用途	示例用法
list_pages	浏览知识图谱；sort: "updated" / updated_since 可查找最近修改的页面	“我这周修改了哪些页面？”
get_page_content	读取页面内容	“获取我的项目笔记”
create_page	使用结构化块添加新页面	“创建一个包含议程事项的会议笔记页面”
update_page	修改页面（追加/替换模式）	“更新我的任务列表”
delete_page	删除页面	“删除旧的草稿页面”
delete_block	根据 UUID 删除块	“删除这个特定的块”
update_block	根据 UUID 编辑块内容	“更新这个特定块的文本”
get_block	根据 UUID 读取块及其属性和子项	“显示这个特定的块”
search	在知识图谱中查找内容	“搜索‘效率技巧’”
query	执行 Logseq DSL 查询（不支持原始 datalog）	“查找所有标记为 #project 的 TODO 任务”
find_pages_by_property	根据属性搜索页面	“查找所有 status = active 的页面”
get_pages_from_namespace	列出命名空间中的页面	“显示 Customer/ 下的所有页面”
get_pages_tree_from_namespace	查看命名空间的层级结构	“以树形结构显示 Projects/”
rename_page	重命名页面并更新引用	“将‘旧名称’重命名为‘新名称’”
get_page_backlinks	查找链接到某个页面的页面	“哪些页面链接到了这个页面？”
insert_nested_block	插入子块/同级块	“在这个任务下添加一个子块”
set_block_properties	为块设置 DB-mode 类属性	“将这个块的状态设为 active” (仅限 DB-mode)
vector_search ⚗️	按含义进行语义搜索	“查找关于影子工作或 Jung 的笔记”
sync_vector_db ⚗️	将向量 DB 与知识图谱文件同步	“更新搜索索引”
vector_db_status ⚗️	查看向量 DB 的健康状态和过期情况	“我的搜索索引是最新的吗？”

⚗️ 需要配置向量搜索——请参阅 VECTOR_SEARCH.md

🎨 智能 Markdown 解析（v1.1.0+）

create_page 和 update_page 工具现在会自动将 Markdown 转换为 Logseq 原生块结构：

Markdown 输入：

---
tags: [project, active]
priority: high
---

# Project Overview
Introduction paragraph here.

## Tasks
- Task 1
  - Subtask A
  - Subtask B
- Task 2

## Code Example
```python
def hello():
    print("Hello Logseq!")
```

结果： 创建结构合理的嵌套块，包括：

• ✅ YAML frontmatter 中的页面属性（tags、priority）
• ✅ 根据标题（#、##、###）生成分层的章节
• ✅ 保留适当缩进的嵌套项目符号列表
• ✅ 将代码块保留为单个块
• ✅ 支持复选框（- [ ] → TODO，- [x] → DONE）

更新模式：

• append（默认）：在现有块之后添加新内容
• replace：清空页面并替换为新内容

🔁 安全重试与大型写入

如果已存在同名页面，create_page 会返回明确错误，而不会让 Logseq 悄悄创建编号重复项（Page(1)、Page 2 等）。这样，超时后的重试就是安全的：如果之前的 create_page 调用超时但实际上已提交，重试时会提示页面已存在，而不会把内容拆散到多个无关页面中。

对于大型写入，建议采用以下模式，而不是一次性进行一个庞大的 create_page 调用：

1. 创建页面时只添加少量内容或不添加内容（create_page 仅提供标题和属性）
2. 使用 update_page（mode: append）分批追加内容
3. 使用 get_page_content 读回内容并验证结果

如果在写入过程中遇到“already exists”错误，请使用 get_page_content 查看已写入的内容，然后通过 update_page 继续，而不是重新创建页面。

---

⚙️ 前置条件

LogSeq 设置

• 已安装并运行 LogSeq
• 已启用 HTTP APIs server（Settings → Features）
• 已启动 API server（🔌 按钮 → “Start server”）
• 已生成 API token（API panel → Authorization tokens）

系统要求

• uv Python 包管理器
• 兼容 MCP 的客户端（Claude Code、Claude Desktop 等）

---

🔧 配置

环境变量

• LOGSEQ_API_TOKEN（必需）：你的 LogSeq API 令牌
• LOGSEQ_API_URL（可选）：服务 URL（默认值：http://localhost:12315）
• LOGSEQ_VERIFY_SSL（可选）：是否验证 https:// LOGSEQ_API_URL 的 TLS 证书。URL 为 https:// 时默认验证；设为 0、false 或 no 可跳过验证，以支持自签名证书。其他任何值都会启用验证。
• LOGSEQ_API_CONNECT_TIMEOUT（可选）：HTTP 连接超时时间，单位为秒（默认值：3）
• LOGSEQ_API_READ_TIMEOUT（可选）：HTTP 读取超时时间，单位为秒（默认值：6）
• LOGSEQ_LOG_LEVEL（可选）：日志详细程度——DEBUG、INFO、WARNING、ERROR 或 CRITICAL（默认值：INFO）。日志输出到 stderr。设为 DEBUG 时，MCP SDK 自身的日志级别仍限制在 INFO，因此不会记录完整的请求负载。
• LOGSEQ_LOG_FILE（可选）：日志文件的路径。未设置时（默认情况），不会写入磁盘。工具调用日志仅记录参数名称和结果大小，因此常规日志中不会出现页面／块内容。
• LOGSEQ_DB_MODE（可选）：设为 true 可启用 DB 模式属性支持。仅适用于 Logseq DB 模式图谱（测试版）。Markdown／基于文件的图谱用户应保持未设置。
• LOGSEQ_EXCLUDE_TAGS（可选）：以逗号分隔的标签列表——带有这些标签的页面会从所有工具中隐藏。请参阅下方的隐私与访问控制。
• LOGSEQ_INCLUDE_NAMESPACES（可选）：以逗号分隔的命名空间允许列表（例如 work,projects）。设置后，只有这些命名空间及其子页面中的页面可访问——其他所有页面，包括没有命名空间的顶层页面，都会从列表／搜索结果中隐藏，并且无法直接访问。请参阅下方的隐私与访问控制。
• LOGSEQ_EXCLUDE_NAMESPACES（可选）：以逗号分隔的命名空间拒绝列表（例如 finance,work/secret）。这些命名空间始终会被屏蔽，且优先级高于允许列表。请参阅下方的隐私与访问控制。
• LOGSEQ_WRITE_NAMESPACES（可选）：以逗号分隔的写入允许列表（例如 Beren）。设置后，写入工具只能以这些命名空间中的页面为目标；其他所有可读取内容均为只读。该规则叠加于包含／排除规则之上，绝不会取代它们。请参阅下方的隐私与访问控制。
• LOGSEQ_CONFIG_FILE（可选）：共享 JSON 配置文件的路径，该文件包含图谱路径、ACL 默认值和 vector 块。环境变量（LOGSEQ_EXCLUDE_TAGS、LOGSEQ_INCLUDE_NAMESPACES、LOGSEQ_EXCLUDE_NAMESPACES、LOGSEQ_WRITE_NAMESPACES）会覆盖此文件中的对应键。
• MCP_HTTP_AUTH_TOKEN（使用 --transport http 时必需）：客户端必须通过 Authorization: Bearer <token> 发送的 Bearer 令牌。没有该令牌，服务将拒绝以 HTTP 模式启动。请参阅通过 HTTP 提供服务。

隐私与访问控制

带有排除标签的页面会对 AI 完全隐藏——它们不会出现在列表、搜索或查询结果中，直接读取也会返回访问被拒绝错误。

通过环境变量快速设置：

LOGSEQ_EXCLUDE_TAGS=private,secret

通过配置文件设置（也用于向量搜索）：

{
  "logseq_graph_path": "/path/to/your/logseq/pages",
  "exclude_tags": ["private", "secret"]
}

使用 LOGSEQ_CONFIG_FILE=/path/to/config.json 指向该文件。

在 Logseq 页面中，为你想要保护的页面添加标签：

tags:: private

排除规则适用于所有工具：list_pages、get_page_content、search、query 和可选的向量搜索。如果你也使用向量搜索，根级别的 exclude_tags 会自动合并到向量索引排除列表中——私密页面绝不会被嵌入。

命名空间访问控制

你可以使用 LOGSEQ_INCLUDE_NAMESPACES 和 LOGSEQ_EXCLUDE_NAMESPACES 限制对特定命名空间的访问。

包含列表（严格允许列表）： 只有列出的命名空间及其子页面可见；其他内容都会隐藏。

LOGSEQ_INCLUDE_NAMESPACES=work,projects

排除列表（拒绝列表）： 即使列出的命名空间出现在包含列表中，也始终会被屏蔽。

LOGSEQ_EXCLUDE_NAMESPACES=work/secret,finance

通过配置文件设置：

{
  "include_namespaces": ["work", "projects"],
  "exclude_namespaces": ["work/secret", "finance"],
  "write_namespaces": ["work/drafts"]
}

写入列表（写入允许列表）： 读取规则允许的内容仍然可读，但写入工具（create_page、update_page、delete_page、rename_page、update_block、delete_block、insert_nested_block、set_block_properties）只能针对这些命名空间中的页面。适用于助手需要读取较大范围内容、但只能编辑其中一部分的情况：

LOGSEQ_INCLUDE_NAMESPACES=Family,Beren
LOGSEQ_WRITE_NAMESPACES=Beren   # reads Family/* and Beren/*, writes only Beren/*

rename_page 要求旧名称和新名称都在写入列表中；块工具会根据块所属页面进行检查（若无法确定所属页面，则会拒绝）。写入列表外的操作会返回 "page 'X' is read-only for this assistant"。写入列表不会扩大读取权限：未被包含列表覆盖的写入命名空间仍会被拒绝（启动时会记录警告）。未设置表示没有额外限制。每次允许的写入都会以 INFO 级别记录为 Write: tool=<name> page=<page name>（仅记录名称，绝不记录内容）。

匹配采用基于路径段且不区分大小写的规则：work 可匹配 work 和 work/projects，但不匹配 workshop。其行为与 LOGSEQ_EXCLUDE_TAGS 一致：列表/搜索结果会静默省略被屏蔽的页面；直接读取、写入、删除和块操作则会返回访问拒绝错误。

访问控制在页面级别执行，并应用于所有工具：列表/搜索/查询结果会省略被屏蔽的页面；直接访问页面/块以及反向链接会被拒绝；向量搜索也会经过筛选。search 和 query 返回的块级结果会解析到其所属页面，因此属于受限页面的块也会从这些结果中筛除。

索引时命名空间范围（仅限向量数据库）。 上述键在查询时生效：每个页面都会被嵌入，受限页面则会从每个响应中筛除。对于向量数据库，你也可以在索引时限定范围——通过配置文件 vector 区块中的 include_namespaces / exclude_namespaces，决定哪些命名空间会被嵌入到数据库中：

{
  "vector": {
    "enabled": true,
    "include_namespaces": ["work"],
    "exclude_namespaces": ["work/secret"]
  }
}

这是全局设置（会影响所有使用者共享的数据库），并且会让不需要的内容完全不写入磁盘，而不是在读取时筛选——适用于不希望嵌入的机密内容，或所有人只关注部分内容、希望缩小索引的情况。匹配规则同样基于路径段且不区分大小写。由于此设置会改变索引内容，因此只有在完整重建索引后才会生效：logseq-sync --rebuild。

🌐 通过 HTTP 提供服务、多配置文件与 TLS

服务器默认使用 stdio 通信——客户端会将其作为子进程启动，大多数用户无需进行其他设置。若要通过网络为沙盒化或远程客户端提供服务，mcp-logseq 可以作为长期运行的 HTTP 服务，并支持 bearer 身份验证、按配置文件隔离和 TLS：

mcp-logseq --transport http --host 127.0.0.1 --port 12320   # requires MCP_HTTP_AUTH_TOKEN

完整的部署指南——包括服务端安全模型、按配置文件运行多实例的模式、单独的 logseq-sync 写入器，以及原生 TLS / 反向代理设置——请参阅 docs/SERVING.md。除非提供 TLS 或传入 --insecure，否则将拒绝通过纯 HTTP 绑定到非环回地址。

替代设置方法

使用 .env 文件

# .env
LOGSEQ_API_TOKEN=your_token_here
LOGSEQ_API_URL=http://localhost:12315

系统环境变量

export LOGSEQ_API_TOKEN=your_token_here
export LOGSEQ_API_URL=http://localhost:12315

---

🔍 验证与测试

测试 LogSeq 连接

uv run --with mcp-logseq python -c "
from mcp_logseq.logseq import LogSeq
api = LogSeq(api_key='your_token')
print(f'Connected! Found {len(api.list_pages())} pages')
"

验证 MCP 注册

claude mcp list  # Should show mcp-logseq

使用 MCP Inspector 调试

npx @modelcontextprotocol/inspector uv run --with mcp-logseq mcp-logseq

---

🐛 故障排除

常见问题

"需要设置 LOGSEQ_API_TOKEN 环境变量"

• ✅ 在 Settings → Features 中启用 HTTP APIs
• ✅ 在 LogSeq 中点击 🔌 按钮 → "Start server"
• ✅ 在 API panel → Authorization tokens 中生成令牌
• ✅ 在配置中验证令牌

"spawn uv ENOENT"（Claude Desktop）

Claude Desktop 找不到 uv。请使用完整路径：

which uv  # Find your uv location

使用完整路径更新配置：

{
  "mcpServers": {
    "mcp-logseq": {
      "command": "/Users/username/.local/bin/uv",
      "args": ["run", "--with", "mcp-logseq", "mcp-logseq"],
      "env": { "LOGSEQ_API_TOKEN": "your_token_here" }
    }
  }
}

常见的 uv 路径：

• Curl 安装：~/.local/bin/uv
• Homebrew：/opt/homebrew/bin/uv
• Pip 安装：使用 which uv 检查

连接问题

• ✅ 确认 LogSeq 正在运行
• ✅ 确认 API 服务已启动（而不只是启用）
• ✅ 检查端口 12315 是否可访问
• ✅ 使用上方的验证命令进行测试

---

👩‍💻 开发

有关本地开发、测试和贡献的信息，请参阅 DEVELOPMENT.md。

---