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.

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):

Variable	Default	Meaning
LOGSEQ_TOKEN	(required)	HTTP API token
LOGSEQ_API_URL	http://localhost:12315	API base URL
LOGSEQ_MCP_READONLY	false	disable all write tools
LOGSEQ_HTTP_TIMEOUT	15	request timeout (seconds)

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

Tool	Kind	Description
search_notes(query, limit=20, status?)	read	Find blocks by keyword; optionally filter by task status
get_page(name)	read	Read a page as an outline
list_open_tasks(project?, priority?, due_before?, overdue?)	read	Open tasks (filtered, sorted by deadline)
list_projects()	read	Project pages + open-task counts
get_journal(date="today")	read	Read a journal entry
get_backlinks(name, include_tags=false)	read	Blocks that link to a page (optionally via #tags)
find_unlinked_mentions(name)	read	Blocks that mention a page's name without linking it
get_outgoing_links(block_uuid)	read	Pages a block links to
get_block_backlinks(block_uuid)	read	Blocks that reference a block via ((uuid))
get_graph_config()	read	Read user/graph configuration
create_task(title, on_project?, on_journal_date?, status?, priority?, scheduled?, deadline?, validate_links?)	write	Create a real task
create_tasks(titles, on_project?, on_journal_date?, status?, priority?, scheduled?, deadline?)	write	Create several tasks at once
set_task_status(task_uuid, status)	write	Move a task's status
set_task_priority(task_uuid, priority?, clear?)	write	Set or clear a task's priority
set_task_schedule(task_uuid, scheduled?, deadline?, clear_scheduled?, clear_deadline?)	write	Set or clear native SCHEDULED/DEADLINE dates
capture_note(text, to="today", validate_links?)	write	Append a note (journal or page)
create_card(question, answer, on_page?, on_journal_date?)	write	Create a flashcard (review in Logseq)
list_due_cards(limit=50)	read	Flashcards due for review (new or past-due)
create_query(query, on_page?, on_journal_date?, title?)	write	Add a live-query dashboard widget
create_project(name, title, description?, tasks?)	write	Scaffold a project page
rename_project(old_name, new_name)	write	Rename a project page
add_link(block_uuid, page_name)	write	Add a [[page]] link to a block
remove_link(block_uuid, page_name)	write	Remove a [[page]] link from a block
link_blocks(source_block_uuid, target_block_uuid)	write	Reference one block from another (((uuid)))
archive_page(name, confirm=false)	destructive	Soft-delete a page (preview first)
remove_block(uuid, confirm=false)	destructive	Remove a block (preview first)

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