Logseq API MCP Server

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，进入 Settings → Features → Developer mode，启用 HTTP APIs server，然后复制显示的令牌。默认端点为 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"
      }
    }
  }
}

重启 Claude Desktop。全部 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	对知识图谱执行原始 Datalog / 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	(必填)	Bearer 身份验证令牌
LOGSEQ_VERIFY_SSL	true	设置为 false 可跳过 TLS 验证
LOGSEQ_DB_MODE	false	启用 Logseq 数据库格式 API 路径
LOGSEQ_EXCLUDE_TAGS	(空)	逗号分隔的标签——含有任一标签的页面将被隐藏
LOGSEQ_LOG_LEVEL	WARNING	日志级别：DEBUG、INFO、WARNING、ERROR

---

DB-Mode

Logseq 较新的数据库格式会将图谱数据存储在 SQLite 中，而不是 Markdown 文件中。设置 LOGSEQ_DB_MODE=true 即可启用 set_block_properties、get_all_page_content 中的 UUID 引用解析，以及由 Datalog 驱动的 find_pages_by_property 查询。不适用于 DB-mode 的工具会返回明确的错误，而不会静默失败。

---

隐私

任何带有 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, ...) 模式可通过 tests/conftest.py 中的 FakeLogseqClient 轻松测试逻辑。以 _ 开头的函数名不会被注册。

---

开发

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

---

Star 历史

---

许可证

MIT — 详见 LICENSE。

---

为 Logseq 和 MCP 社区打造。