AI导哈

Logseq知识图谱API工具集

提供21种工具用于读取、写入、查询和搜索Logseq知识图谱笔记，自动注册Python工具文件。

  • by gustavo-meilus
  • Python
  • 本地部署
  • 31 星标
  • 更新于
在 GitHub 查看 gustavo-meilus/logseq-api-mcp

使用说明

logseq-api-mcp

你的AI助手在每次会话开始时都无视你的Logseq知识图。logseq-api-mcp修复了以下问题：21个用于读取、写入、查询和搜索笔记的工具——在您将Python文件放入时自动注册 src/tools/.

快速开始

步骤1--安装

git clone https://github.com/gustavo-meilus/logseq-api-mcp.git
cd logseq-api-mcp
uv sync

步骤2——配置

cp .env.template .env
# open .env and set LOGSEQ_API_ENDPOINT and LOGSEQ_API_TOKEN

获取您的令牌：打开Logseq，转到 设置→ 特性→ 开发人员模式，启用 HTTP API服务器，并复制所示的令牌。默认端点为 http://127.0.0.1:12315/api.

第3步——连接

// ~/.claude/claude_desktop_config.json
{
  "mcpServers": {
    "logseq-api": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/logseq-api-mcp", "python", "src/server.py"],
      "env": {
        "LOGSEQ_API_ENDPOINT": "http://127.0.0.1:12315/api",
        "LOGSEQ_API_TOKEN": "your_token_here"
      }
    }
  }
}

重新启动克劳德桌面。所有21个工具都是活的。

工具

阅读（12个工具）

工具 它做什么
get_all_pages 每个带有ID、UUID、日志标志和命名空间的页面
get_page_blocks 具有ID、UUID和子计数的分层块树
get_page_links 链接到目标页面的页面
get_page_backlinks 完整的反向链接分析，包括块级引用
get_block_content 带有房产和直系子女的街区细节
get_all_page_content 完整页面：属性、区块、数据库参考展开
get_linked_flashcards 来自一个页面和所有链接页面的问答抽认卡对
search 跨块、页面和文件名的全文搜索
query 针对图形的原始数据日志/DSL查询
find_pages_by_property 按属性键和可选值筛选页面
get_pages_from_namespace Logseq命名空间下的所有页面
get_pages_tree_from_namespace 命名空间页面的嵌套树

书写（10个工具）

工具 它做什么
create_page 创建具有可选属性和格式的页面
delete_page 永久删除页面
rename_page 重命名页面并更新所有引用
update_page 添加或替换现有页面上的内容
append_block_in_page 在页面末尾添加块
edit_block 用UUID替换块的内容
update_block 按UUID更新块内容
insert_nested_block 相对于另一个块插入子块或同级块
delete_block 按UUID删除块
set_block_properties 在块上设置结构化属性（仅限DB模式）

配置

变量 默认值 描述
LOGSEQ_API_ENDPOINT http://127.0.0.1:12315/api Logseq HTTP API基本URL
LOGSEQ_API_TOKEN （必填） 承载身份验证令牌
LOGSEQ_VERIFY_SSL true 设置 false 跳过TLS验证
LOGSEQ_DB_MODE false 启用Logseq数据库格式API路径
LOGSEQ_EXCLUDE_TAGS （空） 逗号分隔的标签——带有任何标签的页面都是隐藏的
LOGSEQ_LOG_LEVEL WARNING 日志级别： DEBUG, INFO, WARNING, ERROR

DB模式

Logseq较新的数据库格式将图形数据存储在SQLite中，而不是markdown文件中。集 LOGSEQ_DB_MODE=true 解锁 set_block_properties，UUID引用解析 get_all_page_content，以及数据日志驱动的查询 find_pages_by_property。不应用于DB模式的工具会返回一个明确的错误，而不是默默地失败。

隐私

任何带有标签的页面 LOGSEQ_EXCLUDE_TAGS 从每次读取操作中消失。强制在查询时运行，因此切换变量会立即生效。

操作 页面被排除时的行为
get_all_pages 列表中缺失的排除页面
search 从结果中删除排除的页面及其块
query 根据排除的页面名称过滤结果
find_pages_by_property 结果已过滤
get_page_backlinks 已删除排除的源页面
get_all_page_content 退货 ❌ Access denied 对于被排除的页面

添加工具

创建 src/tools/my_tool.py。无需导入，无需注册，无需更改配置。发现系统会在下次服务器启动时拾取它。

from typing import List
from mcp.types import TextContent
from src.client.logseq_client import LogseqClient
from src.client.config import LogseqConfig, load_config
from src.logging_setup import get_logger

_log = get_logger(__name__)

async def _run(
    client: LogseqClient, config: LogseqConfig, param: str
) -> List[TextContent]:
    try:
        _log.debug("%s called", __name__)
        result = await client.some_api_method(param)
        return [TextContent(type="text", text=str(result))]
    except Exception as exc:
        _log.error("exception in %s: %s", __name__, exc, exc_info=True)
        return [TextContent(type="text", text=f"❌ Error: {exc}")]

async def my_tool(param: str) -> List[TextContent]:
    """One-line description — this becomes the MCP tool description."""
    cfg = load_config()
    return await _run(LogseqClient(cfg), cfg, param)

这 _run(client, config, ...) 模式通过以下方式保持逻辑可测试性 FakeLogseqClient 在 tests/conftest.py.以开头的函数名 _ 未注册。

发展

uv sync --dev                                                        # all deps
uv run --group test pytest tests/ -v                                 # test suite (345 tests)
uv run --group test pytest tests/ --cov=src --cov-fail-under=85      # coverage gate
uv run ruff check --fix && uv run ruff format                        # lint + format
uv run mypy src/ --ignore-missing-imports                            # type check
uv run bandit -r src/                                                # security scan
uv run mcp dev src/server.py                                         # MCP inspector

星史

许可证

麻省理工学院——见 许可证.

专为Logseq和MCP社区设计。

相关 MCP