---

name: 连接到Logseq version: 1.0.0 description: > 管理通过HTTP API、CLI或MCP服务器连接到Logseq图谱的连接。当用户提及连接到Logseq、API令牌、 图谱路径、连接问题或后端配置时自动触发。处理后端检测、环境设置和连接故障排除。 allowed-tools: 读取，写入，编辑，Bash，Grep，Glob

连接到Logseq

何时使用此技能

此技能在以下情况下自动触发：

• 用户想要将Claude连接到他们的Logseq图谱
• 设置Logseq集成或API令牌
• 故障排除连接问题
• 配置图谱路径或后端
• 用户提到“连接到Logseq”、“Logseq API”、“Logseq令牌”
• 有关HTTP API、CLI或MCP服务器设置的问题

设置脚本：查看{baseDir}/scripts/以获取初始化实用程序。

可用后端

后端	需要运行Logseq	读取	写入	最适合
HTTP API	是	全部	全部	实时，交互式
CLI	否	全部	有限	离线，批量，CI/CD
MCP服务器	是（通过HTTP）	全部	全部	Claude原生工具

快速开始

1. 启用Logseq HTTP API

在Logseq中：

1. 设置 → 高级 → 开发者模式：开
2. 设置 → 高级 → HTTP API服务器：开
3. 设置 → 高级 → 授权令牌 → 创建令牌

2. 设置环境变量

export LOGSEQ_API_TOKEN="你的令牌在这里"

3. 初始化插件

运行设置向导：

python {baseDir}/scripts/init-environment.py

或使用命令：/logseq:init

后端详情

HTTP API（主要）

URL: http://127.0.0.1:12315/api

请求格式：

POST /api
Content-Type: application/json
Authorization: Bearer 你的令牌

{
  "method": "logseq.Editor.getPage",
  "args": ["页面名称"]
}

常用方法：

• logseq.App.getCurrentGraph - 获取当前图谱信息
• logseq.Editor.getPage - 按名称获取页面
• logseq.Editor.getBlock - 按UUID获取区块
• logseq.DB.datascriptQuery - 执行Datalog查询
• logseq.Editor.insertBlock - 创建新区块

CLI (@logseq/cli)

安装：

npm install -g @logseq/cli

用法：

# 查询本地图谱
logseq query "[:find ?title :where [?p :block/title ?title]]" --graph ~/logseq/my-graph

# 与运行中的Logseq（应用内模式）
logseq query "..." --in-app -a 你的令牌

MCP服务器

插件包括一个自定义MCP服务器，将Logseq操作作为Claude工具公开。

位置：servers/logseq-mcp/

构建：

cd servers/logseq-mcp
npm install
npm run build

配置文件

位置：.claude/logseq-expert/env.json

{
  "backend": "auto",
  "http": {
    "url": "http://127.0.0.1:12315",
    "token": "${LOGSEQ_API_TOKEN}"
  },
  "cli": {
    "graphPath": "/path/to/graph",
    "inApp": false
  },
  "mcp": {
    "enabled": true
  },
  "preferences": {
    "defaultGraph": null,
    "confirmWrites": false,
    "backupBeforeWrite": false
  }
}

故障排除

“无法连接到Logseq”

1. 检查Logseq是否运行，HTTP API是否启用
2. 验证端口：默认为12315，检查设置 → 高级
3. 检查防火墙：确保localhost:12315可以访问
4. 手动测试：

   curl -X POST http://127.0.0.1:12315/api \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer 你的令牌" \
     -d '{"method":"logseq.App.getCurrentGraph"}'
   

“认证失败”

1. 验证令牌：检查是否与Logseq设置中的匹配
2. 令牌格式：确保没有多余的空格
3. 环境变量：检查echo $LOGSEQ_API_TOKEN

“CLI未找到”

1. 全局安装：npm install -g @logseq/cli
2. 或使用npx：npx @logseq/cli --help
3. 检查PATH：确保npm全局bin在PATH中

“MCP服务器不工作”

1. 构建服务器：cd servers/logseq-mcp && npm run build
2. 检查Node.js：需要Node 18+
3. 验证HTTP API：MCP服务器内部使用HTTP API

脚本参考

脚本	目的
init-environment.py	交互式设置向导
detect-backend.py	自动检测可用后端
test-connection.py	测试连接
preflight-checks.sh	验证环境

从插件根目录运行脚本：

python logseq-expert/scripts/init-environment.py

安全说明

• 永远不要提交令牌到版本控制
• 使用环境变量存储敏感数据
• 配置中的令牌支持${VAR}语法用于环境变量
• HTTP API默认仅在localhost上监听