logseq-api-mcp

Your AI assistant starts every session blind to your Logseq knowledge graph. logseq-api-mcp fixes that: 21 tools to read, write, query, and search your notes — auto-registered the moment you drop a Python file into `src/tools/`.

]() ]()

<picture> <source media="(prefers-color-scheme: dark)" srcset="assets/architecture-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="assets/architecture-light.svg"> <img src="assets/architecture-light.svg" alt="Architecture: AI Client → logseq-api-mcp (21 tools, privacy) → Logseq API → Knowledge Graph" width="960"> </picture>

Quick Start

Step 1 — Install

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

Step 2 — Configure

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

Getting your token: open Logseq, go to Settings → Features → Developer mode, enable HTTP APIs server, and copy the token shown. The default endpoint is http://127.0.0.1:12315/api.

Step 3 — Connect

// ~/.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"
      }
    }
  }
}

Restart Claude Desktop. All 21 tools are live.

Tools

Read (12 tools)

Write (10 tools)

Configuration

DB-Mode

Logseq's newer database format stores graph data in SQLite rather than markdown files. Set LOGSEQ_DB_MODE=true to unlock set_block_properties, UUID-reference resolution in get_all_page_content, and Datalog-powered queries in find_pages_by_property. Tools that do not apply in DB-mode return a clear error rather than silently failing.

Privacy

Any page tagged with a tag from LOGSEQ_EXCLUDE_TAGS disappears from every read operation. Enforcement runs at query time, so toggling the variable takes effect immediately.

Adding a Tool

Create src/tools/my_tool.py. No imports, no registration, no config changes needed. The discovery system picks it up on the next server start.

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)

The _run(client, config, ...) pattern keeps the logic testable via FakeLogseqClient in tests/conftest.py. Function names starting with _ are not registered.

Development

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 History

License

MIT — see LICENSE.

Made for the Logseq and MCP communities.