mcp-logseq

✨ What You Can Do

Transform your LogSeq knowledge base into an AI-powered workspace! This MCP server enables Claude to seamlessly interact with your LogSeq graphs.

🎯 Real-World Examples

📊 Intelligent Knowledge Management

"Analyze all my project notes from the past month and create a status summary"
"Find pages mentioning 'machine learning' and create a study roadmap"
"Search for incomplete tasks across all my pages"

📝 Automated Content Creation

"Create a new page called 'Today's Standup' with my meeting notes"
"Add today's progress update to my existing project timeline page"  
"Create a weekly review page from my recent notes"

🔍 Smart Research & Analysis

"Compare my notes on React vs Vue and highlight key differences"
"Find all references to 'customer feedback' and summarize themes"
"Create a knowledge map connecting related topics across pages"

🧠 Semantic Search (optional, requires vector setup)

"Find everything I wrote about burnout, even if I didn't use that word"
"What notes relate to my thoughts on deep work?"
"Search across my Dutch and English notes for ideas about productivity"

🤝 Meeting & Documentation Workflow

"Read my meeting notes and create individual task pages for each action item"
"Get my journal entries from this week and create a summary page"
"Search for 'Q4 planning' and organize all related content into a new overview page"

💡 Key Benefits

• Zero Context Switching: Claude works directly with your LogSeq data
• Preserve Your Workflow: No need to export or copy content manually
• Intelligent Organization: AI-powered page creation, linking, and search
• Enhanced Productivity: Automate repetitive knowledge work
• Semantic Vector Search (optional): Find notes by meaning using local Ollama embeddings — no data leaves your machine
• DB-mode Support (opt-in): Read and write class properties on Logseq DB-mode graphs

🚀 Quick Start

Step 1: Enable LogSeq API

1. Settings → Features → Check "Enable HTTP APIs server"
2. Click the API button (🔌) in LogSeq → "Start server"
3. Generate API token: API panel → "Authorization tokens" → Create new

Step 2: Add to Claude (No Installation Required!)

Claude Code

claude mcp add mcp-logseq \
  --env LOGSEQ_API_TOKEN=your_token_here \
  --env LOGSEQ_API_URL=http://localhost:12315 \
  -- uv run --with mcp-logseq mcp-logseq

Claude Desktop

Add to your config file (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "mcp-logseq": {
      "command": "uv",
      "args": ["run", "--with", "mcp-logseq", "mcp-logseq"],
      "env": {
        "LOGSEQ_API_TOKEN": "your_token_here",
        "LOGSEQ_API_URL": "http://localhost:12315"
      }
    }
  }
}

Step 3: Start Using!

"Please help me organize my LogSeq notes. Show me what pages I have."

🔬 Vector Search (Optional)

Semantic search over your Logseq graph using local AI embeddings — find notes by meaning, not just keywords. Searches across all your pages using vector similarity and full-text search combined, with cross-language support.

Powered by Ollama (local embeddings) and LanceDB (embedded vector DB). No data leaves your machine.

→ Full setup guide: VECTOR_SEARCH.md

🛠️ Available Tools

The server provides 16 tools with intelligent markdown parsing, plus 3 optional vector search tools:

⚗️ Requires vector search setup — see VECTOR_SEARCH.md

🎨 Smart Markdown Parsing (v1.1.0+)

The create_page and update_page tools now automatically convert markdown into Logseq's native block structure:

Markdown Input:

---
tags: [project, active]
priority: high
---

# Project Overview
Introduction paragraph here.

## Tasks
- Task 1
  - Subtask A
  - Subtask B
- Task 2

## Code Example
```python
def hello():
    print("Hello Logseq!")
```

Result: Creates properly nested blocks with:

• ✅ Page properties from YAML frontmatter (tags, priority)
• ✅ Hierarchical sections from headings (#, ##, ###)
• ✅ Nested bullet lists with proper indentation
• ✅ Code blocks preserved as single blocks
• ✅ Checkbox support (- [ ] → TODO, - [x] → DONE)

Update Modes:

• append (default): Add new content after existing blocks
• replace: Clear page and replace with new content

🔁 Safe Retries & Large Writes

create_page fails with a clear error if a page with the same title already exists, instead of letting Logseq silently create numbered duplicates (Page(1), Page 2, ...). This makes retries after a timeout safe: if a previous create_page call timed out but actually committed, the retry tells you the page exists rather than fragmenting your content across ghost pages.

For large writes, prefer this pattern over one giant create_page call:

1. Create the page with little or no content (create_page with just the title and properties)
2. Append content in smaller chunks with update_page (mode: append)
3. Read back with get_page_content to verify the result

If you hit the "already exists" error mid-ingest, use get_page_content to see what landed, then continue with update_page instead of re-creating.

⚙️ Prerequisites

LogSeq Setup

• LogSeq installed and running
• HTTP APIs server enabled (Settings → Features)
• API server started (🔌 button → "Start server")
• API token generated (API panel → Authorization tokens)

System Requirements

• uv Python package manager
• MCP-compatible client (Claude Code, Claude Desktop, etc.)

🔧 Configuration

Environment Variables

• LOGSEQ_API_TOKEN (required): Your LogSeq API token
• LOGSEQ_API_URL (optional): Server URL (default: http://localhost:12315)
• LOGSEQ_API_CONNECT_TIMEOUT (optional): HTTP connect timeout in seconds (default: 3)
• LOGSEQ_API_READ_TIMEOUT (optional): HTTP read timeout in seconds (default: 6)
• LOGSEQ_DB_MODE (optional): Set to true to enable DB-mode property support. Only for Logseq DB-mode graphs (beta). Markdown/file-based graph users should leave this unset.
• LOGSEQ_EXCLUDE_TAGS (optional): Comma-separated tags — pages with these tags are hidden from all tools. See Privacy & Access Control below.
• LOGSEQ_INCLUDE_NAMESPACES (optional): Comma-separated namespace allow-list (e.g. work,projects). When set, only pages in these namespaces and their sub-pages are accessible — everything else, including top-level pages without a namespace, is hidden from listings/search and denied on direct access. See Privacy & Access Control below.
• LOGSEQ_EXCLUDE_NAMESPACES (optional): Comma-separated namespace deny-list (e.g. finance,work/secret). These namespaces are always blocked, taking priority over the include list. See Privacy & Access Control below.
• LOGSEQ_CONFIG_FILE (optional): Path to a shared JSON config file holding the graph path, ACL defaults, and the vector block. Env vars (LOGSEQ_EXCLUDE_TAGS, LOGSEQ_INCLUDE_NAMESPACES, LOGSEQ_EXCLUDE_NAMESPACES) override the matching keys in this file.
• MCP_HTTP_AUTH_TOKEN (required for --transport http): Bearer token clients must send as Authorization: Bearer <token>. The server refuses to start in HTTP mode without it. See Serving over HTTP.

Privacy & Access Control

Pages tagged with excluded tags are completely hidden from AI — they won't appear in listings, searches, or queries, and attempting to read them directly returns an access-denied error.

Quick setup via env var:

LOGSEQ_EXCLUDE_TAGS=private,secret