logseq-mcp-server

A TypeScript Model Context Protocol (MCP) server that connects AI assistants to your Logseq knowledge graph. Read, write, search, and manage pages, blocks, journals, and tags through the MCP protocol.

Features

• 17 tools covering Pages, Blocks, Search, Journals, and Graph operations
• Full CRUD for pages and blocks
• Full-text search across the graph
• Batch block insertion with nested children
• Block property management
• Backlink (linked references) retrieval
• Journal page creation and tag listing
• Dual transport: stdio (local) and HTTP (Hono-based, portable across runtimes)

Prerequisites

1. Logseq installed and running
2. HTTP APIs server enabled in Logseq:
   • Settings > Features > Enable "HTTP APIs server"
   • Click the API button > "Start server"
   • Generate a token: API panel > Authorization tokens
3. Node.js >= 18

Quick Start

Claude Desktop

Add to Settings > Developer > Edit Config:

{
  "mcpServers": {
    "logseq": {
      "command": "npx",
      "args": ["logseq-mcp-server"],
      "env": {
        "LOGSEQ_API_TOKEN": "your_token_here"
      }
    }
  }
}

Claude Code

claude mcp add logseq-mcp-server \
  --env LOGSEQ_API_TOKEN=your_token_here \
  -- npx logseq-mcp-server

From Source

git clone https://github.com/user/logseq-mcp-server.git
cd logseq-mcp-server
npm install
npm run build
LOGSEQ_API_TOKEN=your_token npm start

Environment Variables

Variable	Required	Default	Description
LOGSEQ_API_TOKEN	Yes	-	Bearer token from Logseq HTTP API
LOGSEQ_API_URL	No	http://127.0.0.1:12315	Logseq HTTP API URL
TRANSPORT	No	stdio	Transport mode: stdio or http
PORT	No	3000	HTTP port (when TRANSPORT=http)

HTTP Transport

When running with TRANSPORT=http, the server uses Hono with WebStandardStreamableHTTPServerTransport from the MCP SDK.

LOGSEQ_API_TOKEN=your_token TRANSPORT=http PORT=3000 npm start

Endpoints:

• POST|GET|DELETE /mcp - MCP Streamable HTTP protocol
• GET /health - Health check

curl http://localhost:3000/health
# {"status":"ok","server":"logseq-mcp-server"}

Available Tools

Pages

Tool	Description
logseq_list_pages	List pages with filtering (journal, namespace) and pagination
logseq_get_page	Get page metadata by name or UUID
logseq_get_page_content	Get full block tree rendered as indented Markdown
logseq_create_page	Create a new page with optional initial content and properties
logseq_delete_page	Permanently delete a page
logseq_rename_page	Rename a page (updates all references)
logseq_get_page_linked_references	Get backlinks - pages and blocks that reference a page

Blocks

Tool	Description
logseq_get_block	Get a block by UUID with optional children
logseq_insert_block	Insert a block relative to a page or block
logseq_append_block	Append a block at the end of a page
logseq_update_block	Update block content and properties
logseq_remove_block	Permanently remove a block
logseq_move_block	Move a block to a new position
logseq_insert_batch_blocks	Insert multiple blocks at once (supports nesting)
logseq_block_property	Read or write a single block property

Search & Graph

Tool	Description
logseq_search	Full-text search across pages and blocks
logseq_create_journal	Create a journal page for a specific date
logseq_get_graph_info	Get current graph name and path
logseq_get_all_tags	List all tags in the graph

Architecture

src/
├── index.ts              # Entry point, server init, transport selection
├── constants.ts          # Shared constants
├── types.ts              # TypeScript type definitions
├── schemas/
│   └── index.ts          # Zod input validation schemas
├── services/
│   ├── logseq-client.ts  # Logseq HTTP API client
│   └── formatters.ts     # Response formatting helpers
└── tools/
    ├── page-tools.ts     # Page CRUD tools
    ├── block-tools.ts    # Block CRUD tools
    └── search-graph-tools.ts  # Search, journal, graph tools

MCP Client (Claude, etc.)
    ↓ stdio or HTTP
MCP Server (index.ts, Hono)
    ↓ registers tool groups
Tools (page-tools, block-tools, search-graph-tools)
    ↓ calls service methods
LogseqClient (logseq-client.ts)
    ↓ POST /api { method, args }
Logseq HTTP API (local instance)

Development

npm install        # Install dependencies
npm run build      # Compile TypeScript
npm run dev        # Watch mode (tsc --watch)
npm run inspect    # Test with MCP Inspector

License

Apache-2.0