Logseq MCP Tools

Logseq MCP 工具

一个模型上下文协议（MCP）服务，可为 AI 助手提供对 Logseq 知识图谱的结构化访问。

概述

此项目创建了一个 MCP 服务，让 Claude 等 AI 助手能够与您的 Logseq 知识库交互。它提供以下工具：

• 获取所有页面的列表
• 获取特定页面的内容
• 按灵活的日期范围生成日志摘要
• 提取关联页面并探索关联

安装

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 Logseq 工具：

npx -y @smithery/cli install @joelhooks/logseq-mcp-tools --client claude

1. 克隆此仓库
2. 使用 npm、yarn 或 pnpm 安装依赖项：

# Using npm
npm install

# Using yarn
yarn install

# Using pnpm
pnpm install

3. 复制环境模板并配置您的 Logseq 令牌：

cp .env.template .env
# Edit .env with your Logseq authentication token

配置

此项目包含一个 .env.template 文件，您可以将其复制并重命名为 .env。

您可以通过以下步骤找到 Logseq 身份验证令牌：

1. 打开 Logseq
2. 在 Settings > Features > Enable HTTP API 中启用 HTTP API
3. 在 Settings > Features > HTTP API Authentication Token 中设置身份验证令牌

使用方法

运行 MCP 服务

可以使用以下命令启动服务：

# Using the npm script
npm start

# Or directly with tsx
npx tsx index.ts

连接 Claude

Claude Desktop

请遵循 Claude MCP 快速入门指南：

1. 重要：通过 Homebrew（或其他方式）全局安装 Node.js：

brew install node

2. 安装 Claude 桌面应用
3. 打开 Claude 菜单并选择“Settings...”
4. 点击左侧边栏中的“Developer”，然后点击“Edit Config”
5. 这将打开您的 claude_desktop_config.json 文件。将其内容替换为：

{
  "mcpServers": {
    "logseq": {
      "command": "npx",
      "args": [
        "tsx",
        "/path/to/your/index.ts"
      ]
    }
  }
}

重要：将 /path/to/your/index.ts 替换为您的 index.ts 文件的准确绝对路径（例如， /Users/username/Code/logseq-mcp-tools/index.ts）

6. 保存文件并重启 Claude Desktop

现在，您可以与 Claude 聊天，并让它使用您的 Logseq 数据：

• “显示我最近的日志条目”
• “总结我上周的笔记”
• “查找所有与 [主题] 相关的页面”

在 Cursor 中使用 Claude

请遵循 Cursor MCP 文档：

1. 打开 Cursor
2. 在设置中添加一个新的 MCP 服务
3. 输入以下命令：

npx tsx "/path/to/index.ts"

4. 为服务起一个名称，例如“Logseq Tools”

现在，您可以在 Cursor 中使用 Claude 访问您的 Logseq 数据。

在 Anthropic API 中使用 Claude（通用）

使用 Claude API 或命令行工具时，可以通过以下方式添加 MCP 服务：

claude mcp add "logseq" npx tsx "/path/to/index.ts"

Jetbrains Junie 设置

要通过 JetBrains Junie 运行此项目，请按以下步骤操作：

构建 Docker 镜像：

docker build -t logseq-mcp .
# run in project root

然后将以下配置添加到 Junie MCP 配置中：

    "logseq": {
      "command": "c:\\Program Files\\Docker\\Docker\\resources\\bin\\docker.exe",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network=host",
        "-e",
        "LOGSEQ_TOKEN=<Your Token>",
        "-e",
        "LOGSEQ_HOST=host.docker.internal",
        "logseq-mcp"
      ]
    }

可用工具

getAllPages

获取 Logseq 图谱中所有页面的列表。

getPage

获取特定页面的内容。

参数：

• pageName：要获取的页面名称

getJournalSummary

为指定日期范围内的日志条目生成摘要。

参数：

• dateRange：自然语言日期范围，例如“今天”“本周”“上个月”“今年”等。

此工具将：

• 收集指定范围内的日志条目
• 以易读的方式整理条目
• 提取并分析引用的页面／概念
• 显示引用频率最高的概念

createPage

在 Logseq 图谱中创建新页面。

参数：

• pageName：新页面的名称
• content：（可选）页面的初始内容

searchPages

按名称搜索页面。

参数：

• query：用于按页面名称筛选页面的搜索词

getBacklinks

查找引用特定页面的所有页面。

参数：

• pageName：要查找反向链接的页面名称

analyzeGraph

对知识图谱进行全面分析。

参数：

• daysThreshold：（可选）向前回溯多少天来查找“近期”内容（默认值：30）

功能：

• 识别引用频繁的页面
• 跟踪近期更新
• 发现页面集群和关联
• 列出待处理任务
• 建议可能需要的更新

findKnowledgeGaps

分析知识图谱，识别潜在缺口和可改进之处。

参数：

• minReferenceCount：（可选）纳入分析的最少引用次数（默认值：3）
• includeOrphans：（可选）是否在分析中包含孤立页面（默认值：true）

功能：

• 识别被频繁引用但缺失的页面
• 找出需要扩充的内容不足页面
• 列出没有入站链接的孤立页面
• 提供汇总统计数据

analyzeJournalPatterns

分析日志条目随时间变化的模式。

参数：

• timeframe：（可选）分析的时间范围（例如，“最近 30 天”“今年”）
• includeMood：（可选）是否分析情绪模式（如果存在）（默认值：true）
• includeTopics：（可选）是否分析主题模式（默认值：true）

功能：

• 主题趋势及演变
• 情绪模式分析
• 习惯跟踪统计
• 项目进度跟踪

smartQuery

使用 Logseq 的 DataScript 功能执行自然语言查询。

参数：

• request：对要查找内容的自然语言描述
• includeQuery：（可选）在结果中包含生成的 Datalog 查询
• advanced：（可选）使用高级分析功能

功能：

• 页面关联和关系
• 内容聚类
• 任务进度分析
• 概念演变跟踪

suggestConnections

使用 AI 分析知识图谱并推荐有趣的关联。

参数：

• minConfidence：（可选）推荐结果的最低置信度分数（0-1，默认值：0.6）
• maxSuggestions：（可选）返回的最大推荐数量（默认值：10）
• focusArea：（可选）推荐所围绕的主题或领域

功能：

• 发现页面之间的潜在关联
• 识别知识综合机会
• 根据近期兴趣推荐探索路径
• 为推荐结果提供置信度分数

开发

此服务使用以下技术构建：

• Model Context Protocol TypeScript SDK
• 用于参数验证的 Zod
• 用于数据访问的 Logseq HTTP API

如需扩展并添加新工具，请在 index.ts 中添加其他 server.tool() 定义。

故障排除

常见问题

Node.js 版本管理器（fnm、nvm 等）

如果你使用 fnm 或 nvm 等 Node.js 版本管理器，Claude Desktop 将无法正常访问 Node.js 二进制文件，因为它在你的 Shell 环境之外运行，而 PATH 变量是在该环境中修改的。

解决方案：使用 Homebrew 安装系统范围的 Node.js：

brew install node

这样可确保所有应用（包括 Claude Desktop）都能使用 Node.js。

基本故障排除步骤

• 确保 Logseq 正在运行且已启用 HTTP API
• 确认 .env 中的身份验证令牌与 Logseq 中设置的令牌一致
• 检查 Claude 配置中的 index.ts 文件路径是否正确
• 尝试直接在终端中运行 npx tsx index.ts，确认其正常工作

在 Claude Desktop 中查看日志

实时监控日志：

# macOS
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

如需更详细的调试信息，请参阅官方 MCP 调试文档。