MCP-Logseq

An AI bridge for Logseq graphs using the Model Context Protocol (MCP). Connect any MCP-compatible AI assistant (Claude, Cursor, Windsurf, etc.) to your Logseq knowledge base with deep integration for blocks and block references.

Ported from mcp-obsidian with Logseq-specific features:

• Block-first operations — Read, append, and reference individual blocks
• Block references — Create ((block-uuid)) links between blocks
• Context graph — Resolve refs for AI context, get backlinks, build knowledge graphs over time

Quick Start

1. Install Node.js (v18+)

1. Configure your MCP client (e.g. Cursor):

Add to your MCP config (e.g. ~/.cursor/mcp.json or Cursor Settings → MCP):

   {
     "mcpServers": {
       "logseq": {
         "command": "npx",
         "args": ["mcp-logseq", "/path/to/your/logseq/graph"]
       }
     }
   }

Replace /path/to/your/logseq/graph with your actual Logseq graph directory (the folder containing journals/, pages/, .logseq/).

1. Test — Ask your AI:

• "List files in my Logseq graph"
• "Read the page journals/2024_01_15.md"
• "Search for blocks containing 'machine learning'"
• "Get block abc-123-def and show what references it"

Logseq Concepts

Blocks

Logseq content is organized in blocks — each bullet (-) is a block. Blocks have:

• UUID — stable ID (id:: uuid in markdown)
• Content — main text
• Properties — key:: value metadata
• Hierarchy — indentation = parent/child

Block References

• Reference: ((block-uuid)) — links to a block
• Embed: {{embed ((block-uuid))}} — renders block content inline

Use create_block_ref to add refs and read_page with resolveBlockRefs: true to expand them for AI context.

MCP Tools

Page Operations

| Tool | Description | |------|-------------| | read_page | Read page with blocks; optional resolveBlockRefs for AI context | | write_page | Write page (overwrite/append/prepend) | | list_directory | List files and folders | | search_blocks | Search block content and properties | | read_multiple_pages | Batch read (max 10) | | get_frontmatter | Get frontmatter only | | update_frontmatter | Update frontmatter | | delete_note | Delete page (requires confirmation) | | move_note | Move/rename page | | patch_note | Replace string in page | | manage_tags | Add/remove/list tags | | get_notes_info | Metadata without content | | get_graph_stats | Notes, folders, size, recent files |

Block Operations (Logseq-specific)

| Tool | Description | |------|-------------| | read_block | Get block by UUID (searches entire graph) | | append_block | Add block to page (optionally under parent) | | get_block_refs | Get blocks that reference a given block (backlinks) | | create_block_ref | Insert ((uuid)) into a block |

Example: Building a Context Graph

1. Search for relevant blocks: search_blocks with query "project ideas"
2. Read a block: read_block with UUID from results
3. Get backlinks: get_block_refs to see what links to it
4. Create links: create_block_ref to connect related blocks
5. Read with context: read_page with resolveBlockRefs: true to expand refs for AI

Over time, the AI can build a map of your knowledge graph by following block references.

Development

npm install
npm run build
npm start /path/to/graph   # Run with tsx

License

MIT