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

2. 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/).

3. 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"

Related MCP server: Logseq MCP Server

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

Block Operations (Logseq-specific)

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