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

Logseq installed and running
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
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

Logseq MCP Server