Logseq MCP Server

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

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

Blocks

Search & 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