Logseq/MCP/Server/Survey/Report
Properties
- tags
- MCP/Server, ChatGPT/Deep Research/Response
Survey of available Logseq MCP/Servers and their abilities
- 2025-06-27 Fri
- 2025-05-10 Sat
- Most promising
- Not as promising
Logseq/MCP/Server/Py/ruliana/mcp-pkm-logseq
- 2025-05-10 Sat not very mature API. Created by Person/Ronie Uliana, a #Shopify employee
- a unique item is that you configure the server by creating a Logseq page
- Create a page named "MCP PKM Logseq" in your Logseq graph to serve as the guide for AI assistants. Add the following content:
- Description of your tagging system (e.g., which tags represent projects, areas, resources)
- List of frequently used tags and what topics they cover
- Common workflows you use to organize information
- Naming conventions for pages and blocks
- Instructions on how you prefer information to be retrieved
- Examples of useful topic combinations for searching
- Any context about your personal knowledge management approach
- ChatGPT/Deep Research/Response
Overview
- Logseq's Local HTTP API (available when Logseq is running in developer mode) and its underlying graph data can be tapped by external tools to read and write your notes. Several open-source projects provide structured access to Logseq "graphs" (knowledge bases) via these two approaches:
- MCP Servers (HTTP API-based): Standalone servers or plugins using Logseq's local HTTP API to expose functions for listing, querying, creating, or updating pages/blocks. These are often designed to let AI assistants (via the Model Context Protocol, MCP) interact with your Logseq data.
- Direct Node/CLI Tools: Libraries and command-line utilities (often Node.js or ClojureScript-based) that read the Logseq graph files or database directly (e.g. via Datascript) without the Logseq UI. These enable custom queries and automations, sometimes allowing writes by modifying the Markdown/Org files.
- Below we survey the notable open-source solutions, comparing their capabilities (read/write support for pages, blocks, properties), multi-graph handling, update notification features, OS compatibility, installation, usage, limitations, and community status.
HTTP API–Based MCP Servers for Logseq
- These tools act as bridges to Logseq's plugin API over HTTP. They require Logseq Desktop to be running with the HTTP API Server enabled (typically on
localhost:12315 with an API token). The MCP servers run as separate processes (Python or Node) and communicate with Logseq's API to perform actions. - Common features: All expose endpoints or functions to list pages and retrieve page content. Most support creating new pages and updating or deleting existing pages (i.e. write access to Logseq). Many also support operations on blocks (individual bullets) like inserting or editing blocks. Authentication and base URL for Logseq are configurable via environment variables or config files (e.g.
LOGSEQ_API_TOKEN and LOGSEQ_API_URL). Main projects in this category
- An actively maintained Python server (MIT-licensed) exposing a comprehensive set of Logseq operations via MCP. It can list all pages, get page content, create and delete pages, as well as insert and modify blocks. For example, it provides commands like
logseq_create_page (with page name, properties, and a flag for journal pages) and logseq_insert_block (specifying parent block/page and content) for full read/write of the graph. Multiple graphs are nominally supported by some commands – e.g. logseq_get_all_pages accepts a repo parameter to specify the graph – though in practice Logseq's API operates on the currently open graph. No real-time change notifications are implemented; clients can poll (e.g. call logseq_search_blocks periodically) to detect updates. - Status: Active – initial release in early 2025, ~17⭐ on GitHub, with ongoing updates (open to contributions for query support and other enhancements)
- Compatibility: Runs on macOS (tested with Homebrew Python) and likely Linux/Windows (it's pure Python)
- Installation: Straightforward (
pip install mcp-server-logseq) and can be launched via the command-line (python -m mcp_server_logseq) - Configuration: Involves enabling Logseq's API and setting the token as an env var or in your MCP tool config
- A Node.js MCP server (MIT-licensed) that uses the Model Context Protocol SDK and Logseq's HTTP API. It focuses on both basic graph access and higher-level analysis. Core tools include retrieving all pages, getting a page's content, and creating new pages. It also provides advanced read functions: generating summaries of journal entries over a date range, listing backlinks to a page, and even executing free-form Logseq Datalog queries via a
smartQuery tool. (This uses Logseq's Datascript query engine to fulfill natural language requests.) The server can also perform analyses like finding knowledge gaps or suggesting connections between pages using AI heuristics. Write access is supported at the page level (e.g. createPage with optional initial content); however, direct block insertion or editing is not as granular as in the Python solutions. Like others, it doesn't push live updates – queries must be re-run to reflect changes. - Status: Active – created in 2025, ~20⭐. It has a small community (author is a well-known developer) and covers unique analysis use-cases on top of basic graph access
- Compatibility: Developed and tested on macOS (Node.js required; instructions even note installing Node globally via Homebrew) and should work on Linux/Windows (the underlying Logseq API is cross-platform; the project provides config examples for Claude on both Mac and Windows paths)
- Installation: Can use
npm/pnpm to fetch the package or the Smithery CLI (npx @smithery/cli install @joelhooks/logseq-mcp-tools) - Usage: Running the server is done with
npm start or directly via npx tsx index.ts
- A minimalist Python MCP implementation that interfaces with Logseq's API. It provides core operations: listing available graphs, listing pages, fetching a page's content, searching across pages, and basic page management (create/update/delete pages). This covers fundamental read/write needs, though block-level manipulations are not explicitly exposed (the
update_page function presumably writes the entire page content). Setup is similar – you must enable Logseq's dev API and supply the local API URL and token in the environment. - Status: Inactive (only a few commits in 2025) but gained attention for enabling early Logseq–LLM integrations (66⭐)
- Installation: No published PyPI package (install requires cloning the repo; an open issue noted the name not on pip)
- Limitations: No built-in change notification mechanism and license information wasn't provided (unlike others), which might limit community contributions
- An earlier Python MCP server (MIT-licensed) with very similar goals to dailydaniel's. It exposes a rich set of namespace functions under
logseq. – e.g. logseq.get_page, logseq.create_block, logseq.update_block, etc.. Notably, it includes fine-grained block operations like moving blocks and searching blocks by text content, aiming for full parity with Logseq's plugin API. - Status: Mostly inactive (single-digit GitHub stars) and may have been a proof-of-concept or precursor to the more polished dailydaniel project
- Installation: Via source (
pip install -e .) - Usage: Tied to the Cursor IDE/Claude integration
- A specialized MCP server geared towards personal knowledge management scenarios. Instead of exposing every possible Logseq operation, it defines custom "tools" for specific queries – for example,
get_personal_notes(topics, from_date, to_date) to retrieve notes tagged with certain topics, and get_todo_list(...) to fetch TODO items. The emphasis is on read access and guiding an AI assistant with domain-specific instructions (it even provides a logseq://guide resource page with usage notes for the AI). Write access beyond marking todos as done is not emphasized. - Status: Active (v0.2.2 released April 2025) but narrow scope means it might be used alongside a more general solution
- Installation: Via PyPI (
pip install mcp-pkm-logseq) - Requirements: Python 3.12+
- Compatibility: OS-neutral (tested on Mac/Windows for Claude)
- Limitations: No push notifications or multi-graph features (assumes one personal graph context)
Comparison
- All the above MCP servers require the Logseq desktop app running (headless use is not supported by Logseq's API). They all authenticate with the same token and operate on one graph at a time (the one open in Logseq). None of them stream updates or subscribe to changes in real-time – usage is request/response. If an external client needs fresh data, it must call the relevant tool (e.g.
get_page or search) again. In terms of graph coverage, the maintained servers support creating and editing pages and blocks (ensuring true read/write integration) except the PKM-specific one which is read-only. More advanced Logseq features like Datalog queries or block references are only partially supported; e.g., Joel Hooks' server can run arbitrary queries via smartQuery, but others lack direct Datalog query endpoints (a noted gap in current implementations). Supporting those advanced queries and block-level semantics is an area of ongoing development and discussion in the Logseq community.
Node.js and CLI Tools for Graph Access
- An alternative to using Logseq's HTTP API is to work directly with the graph data on disk or via Logseq's code libraries. Logseq graphs are stored as collections of Markdown/Org files with an indexed Datascript database (the
.transit file). The following open-source tools allow querying and sometimes modifying the graph without the Logseq GUI: - A command-line tool that executes Logseq's Datalog queries on a given graph. It is focused on read access – making it easy to search and extract structured data from your notes. You can define custom query rules in EDN and run them via
lq commands. The CLI automatically detects local graphs by scanning the ~/.logseq/graphs directory; running lq graphs lists the available graphs and their paths. You can then specify which graph to query (via a --graph option or a config file to set a default). This means multiple graphs are supported (sequentially) – you can switch context to run queries on different knowledge bases without moving files. Example built-in queries include full-text search on block content, listing all pages with a given property, or finding all TODOs. - Status: Inactive in recent years (released around 2021–2022, 0.9.0 on NPM) but remains a useful solution for complex read-only queries
- Installation: Via npm (
npm install -g logseq-query) - Limitations: Does not support writing to the graph – it doesn't create or edit pages/blocks, because it operates on a static snapshot of the graph's database. If you need to update content, you must do so via other means (or through Logseq itself)
- This is a Node.js package that embeds Logseq's ClojureScript environment for scripting. In essence,
@logseq/nbb-logseq is a customized build of Babashka's NBB (Node Baby…) that bundles Logseq's graph parser and Datascript libraries. It allows developers to run ClojureScript code against their Logseq graph in a Node context, giving access to low-level functions. For example, one can load the graph's database and run Datascript queries programmatically (similar to how plugins query logseq.DB.datascript in the app). This has been used to create scripts for exporting graphs, validating graph data, or running queries in CI pipelines. - Status: Stable but somewhat niche (actively developed up to mid-2023, v1.2.173)
- Installation: Via npm (
npm install -g @logseq/nbb-logseq) - Compatibility: Supports whichever OS Node supports (macOS, Linux, Windows)
- Limitations: Write operations are not straightforward – you can read and analyze the data, but committing changes would require writing back to the Markdown files manually (the Logseq Datascript DB snapshot isn't easily "saved" via NBB)
Person/Jaron Swab/GitHub/lsq
- A community-developed command-line companion to Logseq that focuses on quick capture and editing of journal entries and pages from the terminal. While not an "API" server, LSQ provides a practical way to write to your graph without opening Logseq. It automatically locates the current day's journal file (or any specified page) and lets you append content or open it in your editor of choice. It respects Logseq's file naming conventions and supports both Markdown and Org mode graphs.
- Status: Very active (frequent releases, 80+⭐) and popular for improving capture workflow
- Installation: Cross-platform (compiled Go binary; releases are available for Mac/Linux/Windows)
- Usage: Used interactively or in shell scripts to add notes; e.g. you could bind a hotkey to
lsq -A (append from STDIN) to pipe output of another program into today's journal - Limitations: Offers no read queries beyond simple text search (
-f for page names), and doesn't interface with Logseq's data model (no properties, no relations – those remain text in the file)
- Other Tools and Libraries: A few smaller projects exist:
Person/gpgeek/GitHub/logseq-rust-cli
- A simple Rust-based CLI prototype that used the HTTP API to add a journal entry. This was more of a learning project and supports only a single command.
Logseq/Community/Scripts
- The community has also shared custom scripts (using Python or shell) that manipulate Logseq files directly (thanks to Logseq's plain-text storage, one can automate git syncs or append text). These ad-hoc solutions are not full-fledged APIs, but they illustrate that external automation is possible by treating the graph as plain files. The trade-off is that without the Logseq engine running, you don't get automatic IDs, link ref counts, or queries – you are essentially editing a Markdown notebook. For most robust needs, developers either use the HTTP API via an MCP server or the Datascript approach via
logseq-query/NBB.
Feature Comparison and Practical Considerations
- Read/Write Coverage: The HTTP API-based servers (Logseq running) generally offer the most complete read-write access. With them, you can create pages, modify block content, add metadata properties, and leverage Logseq's own functions (ensuring consistency). The MCP servers by DailyDaniel and apw124 even handle block-level granularity (inserting, moving, and deleting blocks), which covers essentially all editing operations a user can do in Logseq. In contrast, the direct CLI approaches like
lq or NBB are primarily read-only or require manual file edits for writes. If your goal is to both export data and programmatically update it, an HTTP API approach is currently the only turn-key solution (short of writing a custom file-manipulation script). - Access to Multiple Graphs: Logseq itself can only open one graph at a time in the UI, and similarly the local HTTP API operates on that one graph. The MCP servers don't yet provide a seamless multi-graph switch (you'd have to stop Logseq and reopen a different graph, or run multiple Logseq instances on different ports). The ergut server lists a
list_graphs function, but using it still requires switching context for subsequent operations. By contrast, logseq-query (lq) was built with multi-graph in mind – it lists all your local graphs and lets you target any of them for queries. So for cross-graph reporting (without merging them), lq is handy. In principle, one could run multiple MCP server instances on different ports, each connected to a different Logseq graph (if you launch multiple Logseq processes), but this is not a common or officially documented practice. - Polling and Notifications: As of now, none of these tools offer real-time update push or webhook notifications when the graph changes. The Logseq HTTP API does not (yet) provide a subscription mechanism – clients must poll for changes. For example, an integration can periodically call
logseq.get_all_pages or use a lastModified property (if exposed) to detect updates. The community has expressed interest in richer integrations (for instance, syncing Logseq with other systems in real-time), but current solutions are limited to on-demand queries. In practice, if you need near-real-time sync, you might combine file-watching (for direct file edits) with API calls. This is a known limitation and may be addressed in the future if Logseq introduces a headless mode or callback API. - OS Compatibility and Requirements: All surveyed solutions work on macOS. The HTTP API servers have been primarily developed on macOS (driven by early adoption of tools like Cursor IDE and Claude AI on Mac), but they are written in cross-platform languages (Python, Node) and use OS-agnostic network calls. Windows and Linux users have reported success as well. For example, the configuration for Claude's MCP in the Logseq PKM server explicitly shows both macOS and Windows file paths, and most projects use standard libraries. The only caveat is that some installation steps assume macOS paths (e.g. using Homebrew's
uvx launcher or /opt/homebrew Python) – Windows users might need to adjust those (perhaps use the Python executable directly). The Node-based tools require a recent Node.js runtime (e.g. Node 18+ for ESM support). Dependency summary: Python MCP servers need Python 3.11 or 3.12 and the requests library (installed via pip); Node servers need Node and npm/pnpm with packages like @logseq/model or datascript bundled; NBB requires Babashka (which the npm package manages) and Java if you use advanced features; LSQ (Go) comes as a self-contained binary once compiled.- Table 1 summarizes the key environment requirements:
- Logseq/MCP/Server/Py/mcp-server-logseq
- Language/Runtime: Python 3.11+
- Install Method:
pip install mcp-server-logseq - Platform Support: macOS, Linux, Windows (requires Logseq app)
- Logseq/MCP/Server/JS/@joelhooks/logseq-mcp-tools
- Language/Runtime: Node.js (TypeScript)
- Install Method:
npm install (or Smithery CLI) - Platform Support: macOS, Linux, Windows (requires Logseq app)
- Logseq/MCP/Server/Py/ergut/mcp-logseq-server
- Language/Runtime: Python 3.x
- Install Method: Source clone (pip not published)
- Platform Support: macOS, Linux, Windows (requires Logseq app)
- Logseq/MCP/Server/Py/ruliana/mcp-pkm-logseq
- Language/Runtime: Python 3.12+
- Install Method:
pip install mcp-pkm-logseq - Platform Support: macOS, Linux, Windows (requires Logseq app)
- Person/Gabriel Horner/GitHub/logseq-query
- Language/Runtime: Node.js (ClojureScript)
- Install Method:
npm install -g logseq-query - Platform Support: macOS, Linux, Windows
- Logseq/npm/@logseq/nbb-logseq
- Language/Runtime: Node.js (Babashka NBB)
- Install Method:
npm install -g @logseq/nbb-logseq - Platform Support: macOS, Linux, Windows
- Person/Jaron Swab/GitHub/lsq
- Language/Runtime: Go (compiled binary)
- Install Method:
go install or download binary - Platform Support: macOS, Linux, Windows
- Usage Patterns: For MCP servers, usage typically involves running the server in the background and then invoking its functions via an AI assistant or HTTP client. For instance, once Logseq MCP Server is running and configured in Cursor or Claude, you might prompt the AI: "Use the Logseq tool to create a page called ProjectX and add a 'Next Steps' block." The assistant will call the corresponding functions (e.g.
logseq.create_page and logseq.create_block). In a non-AI context, you could cURL these endpoints or write a script to hit the HTTP routes (if documented). The MCP servers are essentially local web servers (often communicating over STDIO when used with an AI app). On the other hand, logseq-query (lq) is used in a terminal session or scripts: e.g. lq q content-search "keyword" to find blocks containing "keyword", and it outputs results to the console. Similarly, nbb-logseq might be used to write a Node script that loads your graph and prints JSON results or writes to a file. LSQ is used interactively or in shell scripts to add notes; e.g. you could bind a hotkey to lsq -A (append from STDIN) to pipe output of another program into today's journal. - Known Limitations and Issues: Since these projects are community-driven and relatively new, there are some limitations to note:
- Logseq API quirks: The HTTP API is essentially the Logseq plugin API. Some functions (like complex Datalog queries or certain property manipulations) might not be exposed or may require workarounds. For example, advanced queries were missing in early versions of the MCP servers, leading to feature requests for things like querying by property or block reference. If your use-case involves something not directly supported (say, renaming a page or retrieving the full block reference context), you might need to script it via multiple calls or contribute an enhancement to the project.
- Concurrent modifications: None of the solutions implement locking or conflict detection. If you are writing to the graph from outside while Logseq is open, be mindful that Logseq will detect file changes and re-index, but rapid or concurrent edits could lead to race conditions. In practice, using the Logseq API (with Logseq running) is safe – it applies changes through Logseq's transaction system. But editing the markdown files directly (as LSQ and some scripts do) while Logseq is also writing to them (e.g. during editing or via API) could cause conflicts that need manual resolution.
- Performance: For very large graphs, pulling all pages or blocks via API might be slow. Some MCP servers offer search functions to narrow results.
logseq-query is efficient at querying the transit DB, but it loads the whole DB into memory each time it runs (which could be a few hundred MB for big graphs). NBB-logseq similarly will incur startup time to load libraries and your data. Caching strategies or partial queries might be needed for heavy use. - Open issues: Many of these projects are in active development and have open issues on GitHub for missing features or bugs. For example, logseq-mcp-tools (Joel's) might have issues filed for edge cases in
smartQuery or Windows path problems, and mcp-server-logseq (DailyDaniel's) has open suggestions for supporting block references and Logseq queries natively. It's wise to check the issue tracker of the repository for any deal-breakers relevant to your needs. All the listed projects are open source (mostly MIT licensed) and welcome contributions.
- Licensing and Community: Nearly all the solutions use permissive licenses (MIT). This means you can integrate them into your own workflows or even modify them to fit your needs. The community around Logseq automation is growing – discussions on Reddit and the Logseq forum indicate an interest in standardizing these tools and potentially merging efforts. As of 2025, you may need to mix and match tools: e.g. use an MCP server for write operations and a CLI query tool for complex reads, depending on what is actively maintained and fits your use-case. Keep an eye on the Logseq official updates too – a planned "Logseq sync server/DB mode" might eventually provide a first-party solution for headless access. Until then, the projects surveyed above are your best options for structured read/write access to Logseq graphs, and they have proven quite capable as practical bridges between Logseq and other systems.
Sources