logseq-mcp

An MCP server that lets an AI agent operate a Logseq (DB) graph through a small set of safe, high-level tools — read notes and tasks, capture notes, create and update tasks, and scaffold projects — without the agent having to know Logseq's internals.

It talks to Logseq's local HTTP API (the same one the desktop app exposes), and encodes the DB-graph conventions that are easy to get wrong (real task statuses, [[page]] vs #tag links, journal date resolution, and soft-delete awareness).

Supported: Logseq DB graphs (the newer SQLite-backed graphs). File/markdown graphs are not supported yet.

Features

• Workflow tools, not raw API. list_open_tasks, create_task, capture_note, create_project, etc. — each does the right multi-step thing under the hood.

• Safe by default. Reads are free; writes are validated; destructive tools (archive_page, remove_block) only soft-delete and require confirm=true after showing a preview.

• Read-only mode. Set LOGSEQ_MCP_READONLY=true to disable all writes.

• Clear failures. Logseq closed, bad token, or bad input each return an actionable message, never a stack trace.

Related MCP server: kontexta

Install

# from source
pip install -e .

# or install as a stable command for daily use (MCP clients point at this)
uv tool install .

# or run without installing (once published)
uvx logseq-mcp
pipx run logseq-mcp

Requires Python 3.10+.

Upgrading a uv tool install: uv tool install . --force can reuse a cached wheel when the version is unchanged, so code edits may not take effect. Use uv tool install . --force --no-cache to force a fresh build, then restart your MCP client so it picks up the new tools.

Configure

1. In Logseq desktop: Settings → Features → enable "HTTP APIs server", start the server, and copy the authorization token.

2. Provide these to the server (via your MCP client's env block, or a local .env for development — see .env.example):

The token is never hardcoded or logged.

MCP client setup

Claude Code

claude mcp add logseq -- logseq-mcp
# then set env, e.g. in .mcp.json:

{
  "mcpServers": {
    "logseq": {
      "command": "logseq-mcp",
      "env": { "LOGSEQ_TOKEN": "your-token-here" }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "logseq": {
      "command": "logseq-mcp",
      "env": { "LOGSEQ_TOKEN": "your-token-here" }
    }
  }
}

(If not installed on PATH, use "command": "python", "args": ["-m", "logseq_mcp"].)

Tools

Resources: logseq://graph, logseq://projects, logseq://today.

Safety model

• Reads never modify anything.

• Writes validate input first and are disabled entirely in read-only mode.

• Destructive tools soft-delete only (recoverable in Logseq's trash), require an explicit confirm=true, and return a preview when confirm is omitted.

• create_task sets the status property (never injects "TODO" text); capture_note is append-only; create_project refuses to overwrite an existing live page.

Troubleshooting

• "Cannot reach Logseq…" — the desktop app isn't running, or the HTTP APIs server is off. Enable it in Settings → Features.

• "Logseq rejected the API token" — LOGSEQ_TOKEN doesn't match the token shown in Logseq's HTTP APIs server settings.

• "supports Logseq DB graphs only" — the open graph is a file/markdown graph; open a DB graph.

• A journal date has no page — open that day in Logseq once (or capture_note to it).

Development

pip install -e ".[dev]"
pytest                      # unit tests (offline)
LOGSEQ_TOKEN=… pytest -m integration   # live tests (needs Logseq running)
ruff check . && mypy src

License

MIT