logseq-mcp
Reads a local Logseq DB graph directly from disk, exposing journals, tasks, pages and blocks as indented Markdown outlines, with block screenshots attached as viewable images. Provides read-only tools to fetch a day's journal, look up a task or block by name/id, list tasks by status, tag or date, search blocks by text, retrieve a page, and fetch individual images, plus graph_info to report which graph is being read.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@logseq-mcp get task web-12 from yesterday's call, with the screenshot"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
logseq-mcp
Lets your AI agent read your Logseq notes, screenshots included, straight from the graph on disk. No running app, no HTTP API, no token, and no way to modify a single note: it is read-only by construction.
You say "do web-12 from yesterday's call" and the agent opens the note itself:
get_task("web-12", date="2026-09-28")
- web-12 [Doing] ‹3f9c21d7›
- The hero image is blurry on mobile
- [image 1] this one
- Contact form sends twice
[image 1] ← the screenshot itself, as an image the model can seeWhy it exists
I take notes in Logseq all day. In client meetings each request becomes a block
named after the project (web-12), with screenshots pasted underneath and
captions like "this one" or "same here". Those notes are the real spec: the
screenshot says which button, the text says what is wrong with it.
Then I open my coding agent and explain it all over again, and the detail is lost in the retelling. I wanted the agent to read the note itself, and above all to look at the screenshots, because the caption alone means nothing. A sentence that sounds perfectly clear, "not the one on top", is ambiguous on a screen with three similar controls. The screenshot settles it.
Logseq's new DB version no longer stores Markdown files, so there is nothing to grep. The existing Logseq MCP servers go through the app's local HTTP API, which means keeping Logseq open, the API server started and a token configured. I wanted something that works from any terminal, with Logseq closed, and that cannot touch my notes by accident.
Related MCP server: Obsidian MCP Second Brain Server
What it does
Journals, tasks, pages and blocks as indented Markdown outlines, in the order you wrote them.
Screenshots come attached as image content, numbered where they appear in the outline, so "this one" keeps pointing at the right picture.
Tasks by status, by tag (on the task or any parent block) or by day. The same task name on several days is expected, not an error.
Reads while Logseq is running, including the notes from the last minutes.
Read-only. It never opens the real database for writing: it reads a copy.
No network. The graph never leaves the machine.
How it works
db.sqlite + WAL ──► snapshot ──► kvs B-tree from the root ──► transit ──► datoms
(locked by Logseq) (copy) (current state only) decode │
▼
MCP tools ◄── outline + images ◄── graphLogseq DB keeps a datascript database
serialized into a single SQLite table, kvs(addr, content, addresses). There is
no public spec for that layout. A reader for an undocumented format mostly fails
quietly: the output looks fine and is wrong. Most of this code exists to turn
quiet failures into loud ones.
Only the current state
kvs is a persistent B-tree. Every write adds new nodes and leaves the old ones
behind until Logseq garbage-collects them. The obvious approach, decoding every
row, works on the first try and is wrong: it resurrects half-typed blocks that no
longer exist, mixed with the real ones, and nothing looks off.
The row at addr = 0 is the root. It holds the address of each index and, in
:eavt-metadata, how many datoms the index must contain. The reader walks
:eavt from the root down to the leaves, ignores every row that is not
reachable, and counts. If the count does not match what the root declares, it
stops: a Logseq update changed the format, and a tree that looks complete and
isn't is worse than an error.
Transit's string cache
Each row is a transit-json document. Transit replaces strings it has already seen
with back-references like "^1", and map keys enter that cache before their
values. Decode a pair in a single Python expression, out[key()] = value(), and
the right-hand side runs first: the cache fills in the wrong order, every later
reference shifts by one, and attribute names come out where values should be.
The decoder does it in two statements and there is a test for exactly that case.
As a second guard, any datom whose attribute is not a keyword aborts the read.
Reading a database that is still open
Logseq holds the file while it runs.
VACUUM INTO was the first attempt: database is locked.
SQLite's backup API was the second: it blocks, waiting for a lock that never comes.
What shipped: copy the files and read the copy. It has to be db.sqlite
together with its WAL, because the last minutes of notes live in the WAL
until a checkpoint. Without it the reader returns a graph that is slightly in
the past, with no sign of it. A hot copy can catch Logseq mid-write, so the copy
goes through integrity_check and is retried once.
The server keeps the decoded graph in memory and reloads it only when the size or modification time of the database or its WAL has changed.
Screenshots are part of the note
Image blocks point to assets/<uuid>.<ext>. The outline marks them as
[image N] right where they sit, and the files are attached after the text in
the same order, so the model reads the caption and sees the picture together.
Up to 8 per call. The rest are one get_image away, with their ids in the
outline.
Install
Requires Python 3.12+ and uv. Tested on macOS with Logseq 2.0.1.
git clone https://github.com/joseguzmann/logseq-mcp.gitIn Claude Code:
claude mcp add logseq -- uv run --directory /path/to/logseq-mcp logseq-mcpIn Claude Desktop, Cursor or any other MCP client:
"logseq": {
"command": "uv",
"args": ["run", "--directory", "/path/to/logseq-mcp", "logseq-mcp"]
}Flag | Env var | Default |
|
|
|
|
| the only graph, if there is just one |
|
| none: only blocks tagged |
|
|
A trap worth knowing. Not every task is tagged
#Task. If you name tasks the way I do and only sometimes tag them,--task-pattern '[a-z][a-z-]*-\d+'makesweb-12count as a task too. Without it, those tasks simply don't show up inlist_tasks, and nothing says why.
Tools
All of them are annotated read-only.
Tool | Returns |
| A day's journal, with its screenshots. |
| A block by its exact text, with its subtree. If the name repeats, the candidates instead of a guess. |
| A block by the |
| Tasks, filtered by status, tag or day. |
| Blocks containing a text, most recent first. |
| A regular page. |
| One screenshot. |
| Which graph is being read and what is in it. |
What to expect
Measured on my own graph: 16,354 datoms, 1,557 entities, 43 journals.
Call | Time |
First call (snapshot + decode + build) | ~60 ms |
Listing or search, graph already loaded | < 10 ms |
A day with 8 screenshots attached (~4 MB) | ~0.6 s |
Every journal in that graph was cross-checked against an independent reader, block by block. The test suite itself runs on synthetic graphs, so it needs neither Logseq nor anybody's notes.
Layout
File | What it solves |
| Decoding transit-json, including the string cache and its ordering |
| Snapshotting a locked database, walking the index, refusing partial data |
| Blocks, pages, journals, inherited tags, task status, image files, outlines |
| The MCP tools, and reloading only when Logseq has written |
| Synthetic graphs with the real on-disk layout, stale rows and all |
Limitations
DB graphs only. For the classic Markdown version, the files are a better source than any server.
Read-only, on purpose. Writing to Logseq's internal format behind the app's back is how you corrupt a graph.
The format is internal and can change with any Logseq release. When it does, the reader stops with a clear error instead of returning partial data.
Block references inside text are resolved to page titles; queries, embeds and properties other than status and tags are not rendered.
Development
uv sync
uv run pytest
uv run ruff check .License
MIT.
Available Tools
8 toolsget_blockBRead-onlyIdempotent
A block by id (the ‹abcd1234› shown in outlines, or a full uuid) with its subtree.
Inputs: id (required), include_images.
get_imageCRead-onlyIdempotent
One screenshot by the id shown next to it.
Inputs: id (required).
get_journalCRead-onlyIdempotent
The journal page of one day as an outline, with its screenshots.
date: "today", "yesterday" or YYYY-MM-DD.
Inputs: date, include_images.
get_pageBRead-onlyIdempotent
A regular (non-journal) page by title, case-insensitive.
Inputs: title (required), include_images.
get_taskBRead-onlyIdempotent
A block by its exact text (e.g. a task called "web-12") with everything under it.
Names are often reused on different days; pass date (YYYY-MM-DD) to pick one.
Inputs: name (required), date, include_images.
graph_infoBRead-onlyIdempotent
Which graph is being read, how big it is and which days have journals.
Inputs: no named parameters. Returns: result
list_tasksARead-onlyIdempotent
Tasks in the graph, oldest first. Filter by status (Todo, Doing, Done...), by tag (tags on the task or any parent block) or by journal day.
Inputs: tag, date, limit, status. Returns: result
searchARead-onlyIdempotent
Blocks whose text contains query (case-insensitive), most recent journals first.
Inputs: query (required), limit. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool maps to a distinct resource or input type: graph metadata, journal, page, block-by-id, task-by-text, search, image. The main overlap is get_block/get_task (both fetch blocks with subtrees) and get_task/search (both locate by text), but the id-vs-exact-text-vs-substring distinction and the descriptions make boundaries workable.
Strong snake_case convention with get_/list_ verb prefixes (get_journal, get_block, get_task, get_page, get_image, list_tasks). Minor deviations: graph_info is noun-only and search has no verb/noun pairing, but they remain readable and predictable.
Eight tools is a well-scoped set for browsing a Logseq graph, with each tool earning its place. No redundant or filler tools.
Read coverage is solid (graph info, journals, pages, blocks, tasks, search, images), but the surface appears read-only with no create/update/delete for blocks, tasks, or pages, and no list_pages/list_journals enumeration. Agents can browse but cannot modify or fully enumerate the graph.
Maintenance
Related MCP Connectors
Your personal library, readable by AI agents: durable snapshots, hybrid search, 46 MCP tools.
Personal context for every AI: search, read, and write back to your private Markdown library.
Persistent memory for AI agents. Hosted cloud connector or local Windows install.
Personal wiki and memory layer for AI assistants. Persistent, structured memory across sessions.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that provides AI assistants with structured access to your Logseq knowledge graph, enabling retrieval, searching, analysis, and creation of content within your personal knowledge base.70MIT
- AlicenseNot gradedqualityDmaintenanceEnables read-only access to Obsidian vaults with semantic search, tag filtering, and metadata queries. Provides secure, intelligent note retrieval and summarization for LLMs without modifying your vault.13 npm13ISC
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with your local Logseq knowledge base through advanced search, content creation, template management, and knowledge organization with privacy-first, local-only operations.53 npm7MIT
- AlicenseBqualityCmaintenanceEnables AI assistants like Claude to directly read, write, search, and navigate your local Logseq knowledge graph, including managing journals, pages, backlinks, and page relationships without manual copy-pasting.115 npm6MIT