Logseq MCP Server

Logseq MCP Server

将你的 Logseq 图谱转化为 AI Agent 的记忆和工作区。 一个适用于 Logseq 的 Model Context Protocol 服务，支持按安全范围写入、在每日日志中记录审计跟踪，并将经过验证的查询作为工具公开。基于 FastMCP 构建（官方 mcp 包的高级 API）。

面向 Logseq 的文件/Markdown（“OG”）版本——纯文本文件也是图谱适合作为 Agent 记忆的原因之一：可通过 git 同步、可搜索、持久耐用、没有厂商锁定。较新的数据库（SQLite）版本改变了底层架构；某些方法在该版本中可能表现不同。

为什么

Agent 需要持久记忆，而你已经在维护一个——你的图谱。缺少的是值得信赖的访问方式：Agent 应该能够广泛读取并有效写入，但绝不能触碰不该动的内容，也不能做任何你无法查看的事情。三个设计选择让这一切成为可能：

• 按命名空间限定写入范围。 Agent 只能在自己的前缀下写入（默认是 byAgent/），另有一个刻意限定范围的跨命名空间通道，只能更改任务的 TODO/DOING/DONE 标记。黑名单页面会被隐藏，并从所有读取结果中删去。
• 在每日日志中记录审计跟踪。 每次成功写入都会在当天的日志中追加一行，例如 22:30 [[byAgent]] wrote [[byAgent/readingList/...]]——检查 Agent 的工作会成为你已有的晨间惯例的一部分。
• 将经过验证的查询作为工具。 将配置中的可靠 Datalog 查询作为命名工具提供（query_week_plan、……），这样 Agent 无需手动编写 datascript，较小型的模型也能保持可靠。

我的使用方式

我在一台始终开机的 Mac mini 上运行一组小型 Claude Code Agent，并让它们访问我实时使用的个人图谱：

• 夜间调研。 手机将链接添加到阅读清单；夜间，Agent 会领取链接（status:: researching），阅读文章——或浅克隆并阅读代码仓库——将结构化摘要写入页面，然后把状态改为 read。
• 晨间简报。 08:30 时，一个小型模型会整理出一页仪表板——夜间阅读内容、周计划进度、当前的 NOW/DOING 任务——并发送一条推送通知。
• 所有人共用一份日志。 人类的任务和 Agent 的审计记录交错出现在同一篇每日日志中：

研究 Agent 写入的页面——属性、摘要、相关性——会直接链接到图谱的其他部分：

flowchart LR
    A[AI agents] -- MCP tools --> S[logseq-mcp]
    S -- HTTP API --> L[Logseq graph]
    S -. audit line per write .-> J[daily journal]
    Y((you)) --> L
    Y -- morning review --> J

要求

• 正在运行的 Logseq，并且已启用本地 HTTP API 服务 （Settings → Features → HTTP APIs server，然后从 🔌 菜单启动）。
• 在 HTTP API 服务设置中创建的授权令牌。

用法

Claude Code

本地（stdio），令牌从环境变量读取：

claude mcp add logseq --scope user --env LOGSEQ_API_TOKEN=<YOUR_TOKEN> -- uvx mcp-server-logseq

或者通过 Streamable HTTP 连接到远程实例（手机和远程会话访问无头主机的方式——参见传输方式）：

claude mcp add logseq --scope user --transport http http://<host>:8000/mcp \
  --header "Authorization: Bearer <LOGSEQ_MCP_HTTP_TOKEN>"

Claude Desktop

{
  "mcpServers": {
    "logseq": {
      "command": "uvx",
      "args": ["mcp-server-logseq"],
      "env": {
        "LOGSEQ_API_TOKEN": "<YOUR_TOKEN>",
        "LOGSEQ_API_URL": "http://127.0.0.1:12315"
      }
    }
  }
}

配置

来源	Token	URL
环境变量	LOGSEQ_API_TOKEN	LOGSEQ_API_URL（默认 http://localhost:12315）
CLI 参数	--api-key	--url

Token 从环境变量或 --api-key 读取；它不会存储在代码中。支持 .env 文件（参见 .env.example）。

配置文件（可选）

默认行为之外的设置通过 TOML 文件指定，文件路径来自 LOGSEQ_MCP_CONFIG（默认 ~/.config/logseq-mcp/config.toml）。自定义查询 存放在同一目录下的 EDN 文件中。不使用配置文件，服务也能正常运行（采用安全、以读取为主的默认设置）；完整注释示例请参见 examples/config.toml。

区块	主要选项
[read]	resolve_depth — 展开 ((block refs)) 的深度
[write]	agent_write_prefix（默认 byAgent）、allow_agents_write_any
[search]	files_path — 图谱文件夹；设置后使用 ripgrep 后端
[blacklist]	pages — 要在所有位置隐藏并编辑的页面（及子页面）
[tasks]	allow_status_change — set_task_status 的开关
[audit_log]	enabled — 将写入操作记录到当天的日志中
[worklog]	enabled、namespace、root_block、exclude、agent_namespace、agent_exclude — 工作日志通道
[queries.<name>]	命名查询：file/内联 query、register_as_tool 等

密钥和 API URL 保留在环境变量中，绝不写入此文件。

传输方式

默认情况下，服务通过 stdio 运行（适用于 Claude Desktop 和其他本地 客户端）。也提供 Streamable HTTP 传输方式，供远程/联网场景使用（例如手机客户端）：

LOGSEQ_MCP_HTTP_TOKEN=<client-secret> \
  mcp-server-logseq --transport streamable-http --host 0.0.0.0 --port 8000
# MCP endpoint: http://<host>:8000/mcp

环境变量：LOGSEQ_MCP_TRANSPORT、LOGSEQ_MCP_HOST、LOGSEQ_MCP_PORT、 LOGSEQ_MCP_HTTP_TOKEN（或 --http-token）。

身份验证

Streamable HTTP 传输必须使用 bearer token：每个请求都必须发送 Authorization: Bearer <LOGSEQ_MCP_HTTP_TOKEN>，否则会收到 401。在未设置 token 的情况下，服务会拒绝以此模式启动。请注意，这与 LOGSEQ_API_TOKEN 是不同的密钥：

密钥	方向
LOGSEQ_API_TOKEN	此服务 → Logseq
LOGSEQ_MCP_HTTP_TOKEN	客户端（手机）→ 此服务

⚠️ bearer token 通过纯 HTTP传输时，只有在已加密的通道上才安全。请勿将原始端口暴露到开放互联网。家庭/无头主机的简便方案是 Tailscale：在主机和客户端上安装它，然后通过加密隧道访问 http://<host>.<tailnet>.ts.net:8000/mcp——无需域名、nginx 或证书。（如果需要 https://，可用 tailscale serve 添加 TLS。）

Docker

构建一次：

docker build -t logseq-mcp .

快速试用（临时运行——停止时 --rm 会移除容器）：

docker run --rm -p 8000:8000 \
  -e LOGSEQ_API_TOKEN=<logseq-token> \
  -e LOGSEQ_MCP_HTTP_TOKEN=<client-secret> \
  -e TZ=Europe/Moscow \
  logseq-mcp

持久化部署（例如无头 Mac mini）——运行一次；重启后 --restart 会自动重新启动：

docker run -d --name logseq-mcp --restart unless-stopped -p 8000:8000 \
  -e LOGSEQ_API_TOKEN=<logseq-token> \
  -e LOGSEQ_MCP_HTTP_TOKEN=<client-secret> \
  -e TZ=Europe/Moscow \
  -e LOGSEQ_MCP_CONFIG=/cfg/config.toml \
  -v /path/to/config-dir:/cfg:ro \
  -v "/path/to/your/graph:/graph:ro" \
  logseq-mcp

• -v .../config-dir:/cfg — 存放 config.toml（以及 queries/、 rules/）的文件夹；在其中设置 files_path = "/graph" 以启用文件搜索。省略挂载和 LOGSEQ_MCP_CONFIG，即可使用默认设置运行。
• -v .../graph:/graph — Logseq 图谱文件夹（只读），用于文件搜索。
• -e TZ=<zone> — 审计日志时间戳使用的本地时区（镜像包含 tzdata； 否则时钟使用 UTC）。

容器在端口 8000 上提供 Streamable HTTP 服务，并与运行在主机上的 Logseq 通信。在 Docker Desktop（macOS/Windows）上，默认的 LOGSEQ_API_URL=http://host.docker.internal:12315 已指向主机； 在 Linux 上添加 --add-host=host.docker.internal:host-gateway（或将 LOGSEQ_API_URL 设置为主机 IP）。请确保 Logseq 的 HTTP API 服务正在运行并处于监听状态。

工具

所有读取输出都会规范化为扁平 JSON 格式，并经过黑名单过滤。读取会无损解析 ((block refs))（保留已解析区块的 uuid/status，便于据此操作）。结果以紧凑 JSON 格式返回，每个区块只包含其已有字段：空字段会省略；只有当 raw_content 与 text 不同时才会出现。在繁忙的日志中，这种形式可将缩进且包含全部字段的形式缩减三分之一。

查找

• search — 对区块内容进行全文搜索（query、regex?、limit?、case_sensitive?、exclude_journals?）。设置了 files_path 时使用 ripgrep 搜索，否则匹配 datascript 内容。
• find_tasks — 按 markers?、tag?、under_tag?（后代）、page?、priority?、limit? 查找任务区块。
• list_pages — 列出命名空间 prefix? 下的页面名称（depth? 限制层级）。发现命名空间的子页面；这些页面独立于父页面，因此不会显示在父页面的 read_page 结果中。仅返回结构，不包含区块内容。
• custom_query — 运行配置中的命名查询（name、inputs?）。
• list_custom_queries — 列出已配置的查询。
• datascript_query — 运行原始 Datalog 查询（query、inputs?、rules?）。

指南

• get_logseq_guide — 返回有关如何查询/写入此图谱的权威指南（涵盖已验证的 Datalog 注意事项：小写名称、前缀后代、标记和日志日期类型、标签与引用、读写范围）。此指南与服务共置，是单一事实来源，可避免 Agent 重新推导（并错误推导）行为。

读取

• read_page — 以规范化区块树形式读取页面（page、depth?）。日期 YYYY-MM-DD 会读取当天的日志，无论图谱采用何种标题格式；不存在的页面会报错，而不是返回空树。
• read_block — 读取区块及其子区块（uuid、depth?）。

写入（仅限 agent 命名空间）

• write_note — 在 agent_write_prefix 下创建/追加/替换页面（subpath、content?、mode?、properties?）。
• set_page_properties — 设置/移除页面属性（subpath、properties）；值为 null 时会移除该属性。
• edit_block — 替换单个区块的内容（uuid、old_content、new_content）。强制执行先读后写：只有 old_content 与区块当前的精确内容匹配时，编辑才会通过。仅限 agent 命名空间。

任务

• create_task — 在 agent 命名空间中创建任务区块（title、agent、project?、marker?、priority?、tags?、plan_page?、blocks_on?、on_page?）。这是创建任务的唯一方式——write_note 会拒绝以任务标记开头的内容。
• set_task_status — 仅更改任务标记（uuid、status）；受 [tasks].allow_status_change 控制。

Worklog（今天的日志；[worklog].enabled）

能够执行工作的 Agent 应该能够在记录其他工作内容的地方——日志中——记录自己的工作，格式与人工手动记录的格式相同：

#_worklog
  #_work/dynamo
    ((6a9eb940-758e-4966-a31d-f91e79c35f42))
      17:50 #_agents/claude/work-scout told how to update

• list_work_projects — 笔记可归入的项目集合（[worklog].namespace 的直接子项，排除 exclude）。
• list_agents — 笔记可使用的签名名称集合，格式为 <runtime>/<name>：来自任意 runtime、位于 Agent 注册表 [worklog].agent_namespace（默认为 _agents）下恰好两层的页面。新建 runtime（_agents/codex/...）无需配置。
• add_journal_note — 在某个项目下，将 HH:MM #<agent> <text> 追加到今天的日志中（参数为 text、work、agent、task?）；如果提供了任务，则嵌套在 ((ref)) 下。
• get_worklog_setup_template — Agent 指令文件（CLAUDE.md、AGENTS.md）中的 worklog 部分：应将任务记录在哪里、何时更新其状态，以及条目格式。仅在用户要求进行设置时调用——在任何会话中说“将 worklog 添加到 CLAUDE.md”就足够了。模板位于 worklog_setup.md。

签名直接写在笔记中，而不是作为分组层级：否则，多个 Agent 在同一项目下记录工作时，会被拆分到各自独立的子树中，每棵子树都有自己的时间顺序。请注意，服务端无法验证调用者身份——每个会话都使用同一个 bearer token，因此 agent 是经列表校验的诚信约定，而非身份标识。它能发现拼写错误，却无法防止冒充。

列表能够保证的是，Agent 不能自行将自己添加到其中。两条规则确保了这一点。注册表位于 Agent 的写入前缀之外，因此 write_note 无法在那里创建页面——如果配置在该范围内，服务端会拒绝启动。此外，只有拥有文件的页面才会计入：在任何笔记中写入 [[_agents/claude/x]] 会让 Logseq 创建一个仅供引用的页面，否则这就足以注册一个名称。因此，注册 Agent 意味着必须在 Logseq 中手动创建其页面。

只有当标题仍是其所在层级的最后一个块时，才会复用该标题：日志顶层块中的 root_block、根块内的项目分组，以及分组内的任务锚点。日志按时间顺序排列，而无论标题位于何处，只要复用它，后续笔记就会继续追加到它下面：上午打开的根块会让晚间笔记显示在下午条目之前；两个 Agent 分别处理两个项目时，新笔记会加入该项目较早的分组，排在另一个项目较晚的条目之前。一旦标题后面出现其他内容，下一个笔记就会开启新的标题——这样一天的记录便会按事情发生的顺序排列，但工作交错时也会重复出现标题。

这是唯一一个会在 agent_write_prefix 之外写入内容的通道，因此它以限制路径范围为代价，遵守一份严格的契约：仅追加、仅限今天的日志、创建的所有内容都位于 root_block 下、work 必须来自枚举值、task 必须是现有任务块，并且时间由服务端标记（调用者无法传入时间，因此恢复运行的 Agent 不能记录记忆中的时间）。以任务标记开头的文本会被拒绝——请使用 create_task。

动态工具

• query_<name> — 每个设置了 register_as_tool = true 的配置查询都会作为独立工具公开。

开发

git clone https://github.com/dailydaniel/logseq-mcp.git
cd logseq-mcp
cp .env.example .env   # fill in LOGSEQ_API_TOKEN
uv sync
uv run mcp-server-logseq

使用 MCP Inspector 检查：

npx @modelcontextprotocol/inspector uv --directory . run mcp-server-logseq

许可证

MIT