MCP Logseq Server

MCP server for LogSeq

Connect Claude to your LogSeq knowledge base. Read, create, and manage pages — with optional semantic vector search and DB-mode graph support.

✨ 你能做什么

将您的LogSeq知识库转化为人工智能驱动的工作空间！此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嵌入按意义查找注释——没有数据离开您的机器
• DB模式支持 *（选择加入）*：在Logseq DB模式图上读写类属性

______________________________________________________________________

🚀 快速开始

步骤1：启用LogSeq API

1. 设置 → 特性 → 选中“启用HTTP API服务器”
2. 点击 API按钮(🔌) 在LogSeq→ “启动服务器”
3. 生成API令牌：API面板→ “授权令牌”→ 创建新的

步骤2：添加到Claude（无需安装！）

克劳德代码

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

克劳德桌面

添加到配置文件(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"
      }
    }
  }
}

第三步：开始使用！

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

______________________________________________________________________

🔬 矢量搜索（可选）

使用本地AI嵌入在Logseq图上进行语义搜索——按含义而不仅仅是关键字查找注释。使用矢量相似性和全文搜索相结合的方式在所有页面上进行搜索，并支持跨语言。

由...驱动 奥拉玛 （局部嵌入）和 兰斯数据库 （嵌入式矢量数据库）。没有数据离开你的机器。

→ 完整设置指南：VECTOR_SEARCH.md

______________________________________________________________________

🛠️ 可用工具

该服务器提供16个具有智能markdown解析的工具，以及3个可选的矢量搜索工具：

⚗️ *需要矢量搜索设置--请参阅 矢量_搜索.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

def hello(): print("Hello Logseq!")

Result: Creates properly nested blocks with:

• ✅ Page properties from YAML frontmatter (tags, priority)
• ✅ Hierarchical sections from headings (#, ##, ###)
• ✅ Nested bullet lists with proper indentation
• ✅ Code blocks preserved as single blocks
• ✅ Checkbox support (- [ ] → TODO, - [x] → DONE)

Update Modes:

• append (default): Add new content after existing blocks
• replace: Clear page and replace with new content

⚙️ Prerequisites

LogSeq Setup

• LogSeq installed and running
• HTTP APIs server enabled (Settings → Features)
• API server started (🔌 button → "Start server")
• API token generated (API panel → Authorization tokens)

System Requirements

• uv Python package manager
• MCP-compatible client (Claude Code, Claude Desktop, etc.)

🔧 Configuration

Environment Variables

• LOGSEQ_API_TOKEN (required): Your LogSeq API token
• LOGSEQ_API_URL (optional): Server URL (default: http://localhost:12315)
• LOGSEQ_DB_MODE (optional): Set to true to enable DB-mode property support. Only for Logseq DB-mode graphs (beta). Markdown/file-based graph users should leave this unset.
• LOGSEQ_EXCLUDE_TAGS (optional): Comma-separated tags — pages with these tags are hidden from all tools. See Privacy & Access Control below.

Privacy & Access Control

Pages tagged with excluded tags are completely hidden from AI — they won't appear in listings, searches, or queries, and attempting to read them directly returns an access-denied error.

Quick setup via env var:

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 根目录下的私有页会自动合并到向量索引排除列表中——私有页永远不会嵌入。

替代设置方法

使用.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检查器进行调试

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

______________________________________________________________________

🐛 故障排除

常见问题

“需要LOGSEQ_API_TOKEN环境变量”

• ✅ 在中启用HTTP API 设置→ 特性
• ✅ 点击 🔌 按钮 → “启动服务器” 在LogSeq
• ✅ 在中生成令牌 API面板→ 授权令牌
• ✅ 验证配置中的令牌

“spawn uv ENOONT”（克劳德桌面）

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" }
    }
  }
}

常见紫外线位置：

• 卷曲安装： ~/.local/bin/uv
• 自制： /opt/homebrew/bin/uv
• Pip安装：检查 which uv

连接问题

• ✅ 确认LogSeq正在运行
• ✅ 验证API服务器是否 开始 （不仅仅是启用）
• ✅ 检查端口12315是否可访问
• ✅ 使用上述验证命令进行测试

______________________________________________________________________

👩‍💻 发展

有关本地开发、测试和贡献，请参阅 Developpent.md.

______________________________________________________________________

Ready to supercharge your LogSeq workflow with AI?

⭐ Star this repo if you find it helpful!