使用说明

Logseq MCP服务器

MCP（模型上下文协议）服务器，用于与Logseq图交互，使AI助手能够读取、创建和操作Logseq内容。

特性

区块操作：创建、更新和删除块
页面管理：创建页面、检索页面内容、搜索页面
查询执行：对Logseq图执行Datalog查询
日志支持：通过自动格式转换按日期访问日记页面
隐私优先日志：自动清除日志中的敏感数据
MCP协议：完全符合模型上下文协议规范

快速设置

自动设置（推荐）

我们提供了一个安装向导，将指导您完成安装：

# Clone the repository
git clone https://github.com/yourusername/logseq-mcp.git
cd logseq-mcp

# Run the setup wizard
./deploy.sh

安装向导将：

检查你的Python版本（需要3.13以上）
安装uv包管理器（如果不存在）
安装所有依赖项
配置Logseq API连接
测试与Logseq的连接
为Claude Desktop或Cline生成配置

先决条件

Python 3.13+
启用API的Logseq
uv（推荐）或pip用于包装管理

手动安装

如果您更喜欢手动设置而不是使用安装向导：

使用紫外线（推荐）

# Clone the repository
git clone https://github.com/yourusername/logseq-mcp.git
cd logseq-mcp

# Install dependencies
uv pip install --system -e .

# Install development dependencies (optional)
uv pip install --system -e ".[dev]"

使用pip

# Clone the repository
git clone https://github.com/yourusername/logseq-mcp.git
cd logseq-mcp

# Install dependencies
pip install -e .

# Install development dependencies (optional)
pip install -e ".[dev]"

配置

Logseq配置

复制示例环境文件：
```
cp env/.env.example env/.env
```

在中配置Logseq API设置 env/.env:

LOGSEQ_API_HOST=localhost
LOGSEQ_API_PORT=12315

在Logseq设置中启用Logseq API

Claude桌面配置

安装向导(./deploy.sh)将为您生成配置。如果需要手动配置，请将以下内容添加到Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "logseq": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/logseq-mcp",
        "run",
        "--with",
        ".",
        "--refresh",
        "--python",
        "3.13",
        "python",
        "-m",
        "logseq_mcp_server"
      ],
      "env": {
        "LOGSEQ_API_HOST": "localhost",
        "LOGSEQ_API_PORT": "12315",
        "LOGSEQ_MCP_LOG_LEVEL": "INFO",
        "LOGSEQ_MCP_PROJECT_ROOT": "/path/to/logseq-mcp"
      }
    }
  }
}

安全说明：默认情况下禁用删除操作，以防止意外或 AI引发数据丢失。添加 "LOGSEQ_DELETE_ENABLED": "true" 到 env 仅限块当您明确希望AI助手能够删除块时。

重要说明:

替换所有实例 /path/to/logseq-mcp 带有克隆存储库的实际绝对路径（在args和env中）
这 --directory 参数设置UV的工作目录
这 --with . 参数告诉UV在运行之前安装本地程序包
这 --refresh flag确保UV使用最新代码（在开发过程中很重要）
这 LOGSEQ_MCP_PROJECT_ROOT 环境变量确保日志保存在项目目录中
在启动Claude Desktop之前，确保Logseq在启用API服务器的情况下运行
如果您的Logseq API需要令牌，则可能需要配置身份验证

要启用 delete_block 工具，添加 LOGSEQ_DELETE_ENABLED 到 env 块：

"env": {
  "LOGSEQ_API_HOST": "localhost",
  "LOGSEQ_API_PORT": "12315",
  "LOGSEQ_DELETE_ENABLED": "true"
}

故障排除:

如果您看到有关缓存代码的错误，请运行 uv cache clean 清除UV缓存
检查日志 logs/ 详细错误信息的项目目录

更新配置后，重新启动Claude Desktop以连接到Logseq MCP服务器。

Cline（VS代码扩展）配置

对于Cline用户，安装向导将提供配置。您还可以在VS Code中手动将服务器添加到您的Cline设置中：

打开VS代码设置
导航到扩展>临床>MCP服务器
添加安装向导提供的配置

日志记录和隐私

服务器包括以隐私为中心的日志记录，默认情况下可以保护您的个人数据：

隐私功能

默认隐私模式：页面名称、内容和查询等个人数据会自动清理
自动日志轮换：通过可配置的大小/基于时间的旋转来防止磁盘空间问题
可配置的保留：设置自动删除前保留日志的时间

日志记录模式

隐私模式 （默认）：对敏感信息进行消毒
- 页面名称： "My Private Notes" → "My P***otes" （保留部分可见性）
- 内容：已替换为 [content_123_chars]
- 查询：隐藏为 [datalog_query_45_chars]
- 文件路径： /Users/john/Documents → /Users/***/Documents
- 块ID：匿名为 block_a1b2c3 （一致散列）
调试模式：用于故障排除的完整日志记录
- 启用 LOGSEQ_MCP_LOG_MODE=debug
- 显示完整数据（仅在需要时使用）
极简模式：仅错误和警告
- 启用 LOGSEQ_MCP_LOG_MODE=minimal

配置

# Environment variables
LOGSEQ_MCP_LOG_MODE=privacy          # privacy, debug, or minimal (default: privacy)
LOGSEQ_MCP_LOG_LEVEL=INFO            # DEBUG, INFO, WARNING, ERROR (default: INFO)
LOGSEQ_MCP_LOG_RETENTION_DAYS=7      # Days to keep logs (default: none)
LOGSEQ_MCP_LOG_MAX_SIZE=10MB         # Max file size before rotation (default: 10MB)
LOGSEQ_MCP_DEBUG=true                # Enable console output (default: false)
LOGSEQ_MCP_LOG_FILE=/custom/path.log # Custom log location (optional)

隐私模式日志条目示例

{
  "timestamp": "2025-01-15T10:30:45Z",
  "level": "INFO",
  "logger": "logseq_mcp_server.logging_config",
  "message": "Tool get_page completed successfully",
  "tool_name": "get_page",
  "arguments": {
    "name": "My P***nal"
  },
  "result": {
    "success": true,
    "page": {
      "originalName": "My P***nal",
      "uuid": "block_7d4e8c"
    }
  },
  "duration_ms": 45
}

查看日志

# View logs in real-time
tail -f logs/logseq-mcp.log

# Search logs while respecting privacy
grep '"level": "ERROR"' logs/logseq-mcp.log

临时调试模式

排除问题时：

# Run with debug logging temporarily
LOGSEQ_MCP_LOG_MODE=debug python -m logseq_mcp_server

# Or in Claude Desktop config (temporarily):
"env": {
  "LOGSEQ_MCP_LOG_MODE": "debug",
  "LOGSEQ_MCP_LOG_RETENTION_DAYS": "1"
}

重要：请记住在调试后切换回隐私模式，以保护您的个人数据。

用法

运行服务器

# Run with default stdio transport
python -m logseq_mcp_server

# Run with SSE transport
LOGSEQ_MCP_TRANSPORT=sse python -m logseq_mcp_server

# Run with MCP CLI
mcp run src/logseq_mcp_server/server.py

可用工具

区块操作

create_block：在页面中创建新块
update_block：更新现有块的内容或属性
delete_block：删除块 （默认情况下禁用；需要 LOGSEQ_DELETE_ENABLED=true)

页面操作

create_page：创建新页面
get_all_pages：获取当前图形中的所有页面
get_page：检索页面及其内容
get_journal_page：按日期获取日记页（支持各种日期格式）
search_pages：按查询搜索页面

查询操作

execute_query：执行数据日志查询（支持参数化查询的可选输入参数）

使用日记页面

这 get_journal_page 该工具提供了一种按日期检索日志页面的便捷方法，自动将各种日期格式转换为Logseq的日志页面命名约定。

支持的日期格式

该工具接受多种格式的日期：

ISO格式: "2023-12-25"
美国格式: "12/25/2023"
欧盟格式: "25/12/2023"
缩写预格式化: "Dec 25th, 2023"
Python日期/日期时间对象 （直接使用API时）

示例用法

// Get today's journal page
{
  "tool": "get_journal_page",
  "arguments": {
    "date": "2024-01-15"
  }
}

// Get journal with blocks
{
  "tool": "get_journal_page",
  "arguments": {
    "date": "01/15/2024",
    "include_children": true
  }
}

该工具将提供的日期转换为Logseq的缩写日志格式（例如。， "Dec 25th, 2023")在获取页面之前。

执行数据日志查询

这 execute_query 该工具对图形运行Datalog查询。它还接受可选 inputs 用于参数化查询的数组。

// Simple query
{
  "tool": "execute_query",
  "arguments": {
    "query": "[:find ?name :where [?p :block/name ?name]]"
  }
}

// Parameterized query
{
  "tool": "execute_query",
  "arguments": {
    "query": "[:find ?b :in $ ?tag :where [?b :block/refs ?r] [?r :block/name ?tag]]",
    "inputs": ["meeting"]
  }
}

故障排除

如果在安装过程中遇到问题：

Python版本：确保您安装了Python 3.13+
```
python3 --version
```
API日志：确保在Logseq中启用了API服务器：
- 设置>高级>启用“API服务器”
- 默认端口为12315

连接问题：手动测试连接：

cd logseq-mcp
python tests/tools/test_logseq.py get-all-pages --limit 5

日志：检查日志目录以获取详细的错误信息：
```
tail -f logs/logseq-mcp.log
```

清洁安装：如果所有其他方法都失败，请尝试全新安装：

# Remove existing installation
rm -rf .venv build dist *.egg-info

# Run setup wizard again
./deploy.sh

发展

使用测试线束进行测试

独立测试线束(tests/tools/test_logseq.py)用于在不经过MCP协议的情况下对Logseq API调用进行快速测试和调试。此工具可用于：

调试API连接问题
直接测试原始API方法
以交互方式探索Logseq API功能
在实施MCP工具之前验证API响应

使用示例：

# Test specific methods
python tests/tools/test_logseq.py get-page "MCP Server"
python tests/tools/test_logseq.py get-page "Test Page" --show-raw
python tests/tools/test_logseq.py get-all-pages --limit 5
python tests/tools/test_logseq.py search "test"

# Test journal pages
python tests/tools/test_logseq.py get-page "December 25th, 2023"  # Get journal by formatted name

# Raw API calls
python tests/tools/test_logseq.py raw logseq.Editor.getCurrentGraph
python tests/tools/test_logseq.py raw logseq.Editor.getPage "My Page"

# Interactive REPL mode
python tests/tools/test_logseq.py interactive

# Verbose mode for debugging
python tests/tools/test_logseq.py get-page "MCP Server" --verbose

测试线束提供：

直接访问LogseqClient，无需MCP开销
打印精美的JSON输出
交互式REPL用于探索
完整的请求/响应日志记录
交互模式下的命令历史记录

关于Logseq API参数的重要说明

大多数Logseq API方法都希望参数包装在数组中，即使是单个值：

正确: logseq.Editor.getPage ["MCP Server"]
不正确: logseq.Editor.getPage "MCP Server"

需要数组格式的方法：getPage、getPageBlocksTree、getBlock、removeBlock、createPage、insertBlock、updateBlock。使用字符串格式的方法：search，q（查询）。

运行测试

# Run all tests
pytest

# Run with coverage
pytest --cov=src/logseq_mcp_server tests/

# Run specific test
pytest tests/unit/test_tools.py -v

代码质量

# Run linter
ruff check src/ tests/

# Format code
ruff format src/ tests/

贡献

分叉存储库
创建要素分支(git checkout -b feat/amazing-feature)
使用常规提交提交更改
推到分支(git push origin feat/amazing-feature)
打开拉取请求

约定式提交

此项目使用常规提交。示例：

feat(tools): add block creation tool
fix(api): handle empty query results
docs(readme): update installation instructions

看 CLAUDE.md 详细的开发指南。

许可证

致谢

与 MCP-SDK
与集成 Logseq