This server allows AI agents to interact with a local Logseq instance programmatically to manage pages and blocks in a graph.
Pages Operations:
Get a list of all pages
Retrieve, create, or delete specific pages
Handle journal pages with automatic date formatting and attributes
Get linked references to a page
Block Operations:
Retrieve, create, update, move, or remove blocks
Insert blocks as children or siblings of other blocks
Manage hierarchical structures and block-specific attributes
Move blocks with their children
Additional Functions:
Search for blocks matching specific queries
Retrieve blocks that reference other pages or journal entries
Enables AI agents to interact with a local Logseq instance by providing tools for managing pages and blocks, including creating, updating, deleting, and searching content within a Logseq graph.
Logseq MCP Tools
This project provides a set of Model Context Protocol (MCP) tools that enable AI agents to interact with your local Logseq instance.
Installation
Ensure you have Python 3.11+ installed
Clone this repository
Install dependencies:
pip install -e .
Setup
Make sure your Logseq has the API enabled.
In Logseq, go to Settings > Advanced > Developer mode > Enable Developer mode
Then, go to Plugins > Turn on Logseq Developer Plugin
Also set an API token in the Advanced settings
Restart Logseq
Configure the MCP server in your Cursor MCP configuration file (typically at
~/.cursor/mcp.json
):{ "mcpServers": { "logseq": { "command": "/opt/homebrew/bin/uvx", "args": ["logseq-mcp"], "env": { "LOGSEQ_API_URL": "http://localhost:12315", "LOGSEQ_TOKEN": "your-token-here" } } } }
OR
Configure Claude Code to use the MCP server with:
Select scope
Select Stdio
LOGSEQ_API_URL=http://localhost:12315 LOGSEQ_TOKEN=your-token-here /opt/homebrew/bin/uvx logseq-mcp
Using with Cursor and Claude
Adding to Cursor's MCP Tools
Configure the MCP server as shown above in the Setup section
Open Cursor and go to the MCP panel (sidebar)
The Logseq tool should appear in your list of available tools
Using with Claude
When using Claude in Cursor, you'll need to inform it that you have Logseq tools available with a prompt similar to:
"You have access to Logseq tools that can help you interact with my Logseq graph. You can use functions like logseq.get_all_pages(), logseq.get_page(name), logseq.create_page(name), etc."
Available Tools
All tools are available under the logseq
namespace:
Pages
logseq.get_all_pages
: Get a list of all pages in the Logseq graphlogseq.get_page
: Get a specific page by namelogseq.create_page
: Create a new pagelogseq.delete_page
: Delete a page and all its blocks
Blocks
logseq.get_page_blocks
: Get all blocks from a specific pagelogseq.get_block
: Get a specific block by IDlogseq.create_block
: Create a new block on a pagelogseq.insert_block
: Insert a block as a child of another blocklogseq.update_block
: Update an existing blocklogseq.move_block
: Move a block to a different locationlogseq.remove_block
: Remove a block and all its childrenlogseq.search_blocks
: Search for blocks matching a query
Working with Logseq
Journal Pages
Journal pages in Logseq have a specific format and attributes:
Use the format "mmm dth, yyyy" (e.g., "Apr 4th, 2025") when creating or accessing journal pages
Journal pages are automatically formatted by Logseq with proper dating
Journal pages have special attributes that are automatically set by Logseq:
journal?
: true - Indicates this is a journal pagejournalDay
: YYYYMMDD - The date in numeric format (e.g., 20250404 for April 4, 2025)
Example:
await logseq.create_page("Apr 4th, 2025")
Important: You do not need to manually set the journal?
or journalDay
attributes. Simply creating a page with the proper date format (e.g., "Apr 4th, 2025") will automatically configure it as a journal page with the appropriate attributes.
Block Structure and Formatting
Blocks in Logseq have some important characteristics to understand:
Automatic Bullets: All blocks are automatically rendered as bullet points in the Logseq UI
Page Links: Create links using double brackets:
[[Page Name]]
Hierarchical Blocks:
Block structure data contains hierarchical information:
parent
: The parent block's IDlevel
: The indentation level (1 for top-level, 2+ for indented blocks)left
: The block to the left (typically the parent for indented blocks)
Block Content: When creating blocks, you can include text formatting:
Basic Markdown is supported (bold, italic, etc.)
Bullet points within a block may have limited support
Multi-line content is supported but may be subject to Logseq's parsing rules
Journal Blocks: Blocks created in journal pages inherit special attributes:
journal?
: truejournalDay
: YYYYMMDD - Same as the journal page
Note: Like journal pages, these block attributes are automatically handled by Logseq. You don't need to manually set the journal?
or journalDay
attributes when creating blocks on journal pages.
Example Usage for Common Tasks
Working with the Cursor agent: When you have Logseq MCP tools configured in Cursor, you can give the agent prompts like:
"Create a new page called 'Meeting Notes' with bullet points for today's agenda"
"Add today's tasks to my journal page with a 'Tasks' section"
"Update today's journal entry with [[Project Plan]], set its child element to 'Completed milestone 1'"
"Search my graph for blocks about 'python projects' and organize them on a new page"
The agent will use the appropriate Logseq tools to carry out these operations on your graph.
local-only server
The server can only run on the client's local machine because it depends on local resources.
Tools
A Model Context Protocol server that enables AI agents to interact with local Logseq knowledge graphs, supporting operations like creating/editing pages and blocks, searching content, and managing journal entries.
Related MCP Servers
- -securityFlicense-qualityA 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.Last updated -51
- AsecurityAlicenseAqualityA Model Context Protocol server that enables AI assistants to interact with Confluence content, supporting operations like retrieving, searching, creating, and updating pages and spaces.Last updated -98MIT License
- -securityFlicense-qualityA comprehensive Model Context Protocol server implementation that enables AI assistants to interact with file systems, databases, GitHub repositories, web resources, and system tools while maintaining security and control.Last updated -361
CodeAlive MCPofficial
-securityAlicense-qualityA Model Context Protocol server that enhances AI agents by providing deep semantic understanding of codebases, enabling more intelligent interactions through advanced code search and contextual awareness.Last updated -55MIT License