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

def hello():

print("Hello Logseq!")

// Code block

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

---

⚙️ 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_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.

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

Via config file (also used for vector search):

{
  "logseq_graph_path": "/path/to/your/logseq/pages",
  "exclude_tags": ["private", "secret"]
}

Point to it with LOGSEQ_CONFIG_FILE=/path/to/config.json.

In your Logseq pages, tag any page you want to protect:

tags:: private

The exclusion applies to all tools: list_pages, get_page_content, search, query, and the optional vector search. If you also use vector search, exclude_tags at the root is automatically merged into the vector index exclusion list — private pages are never embedded.

Alternative Setup Methods

Using .env file

# .env
LOGSEQ_API_TOKEN=your_token_here
LOGSEQ_API_URL=http://localhost:12315

System environment variables

export LOGSEQ_API_TOKEN=your_token_here
export LOGSEQ_API_URL=http://localhost:12315

---

🔍 Verification & Testing

Test LogSeq Connection

uv run --with mcp-logseq python -c "
from mcp_logseq.logseq import LogSeq
api = LogSeq(api_key='your_token')
print(f'Connected! Found {len(api.list_pages())} pages')
"

Verify MCP Registration

claude mcp list  # Should show mcp-logseq

Debug with MCP Inspector

npx @modelcontextprotocol/inspector uv run --with mcp-logseq mcp-logseq

---

🐛 Troubleshooting

Common Issues

"LOGSEQ_API_TOKEN environment variable required"

• ✅ Enable HTTP APIs in Settings → Features
• ✅ Click 🔌 button → "Start server" in LogSeq
• ✅ Generate token in API panel → Authorization tokens
• ✅ Verify token in your configuration

"spawn uv ENOENT" (Claude Desktop)

Claude Desktop can't find uv. Use the full path:

which uv  # Find your uv location

Update config with full path:

{
  "mcpServers": {
    "mcp-logseq": {
      "command": "/Users/username/.local/bin/uv",
      "args": ["run", "--with", "mcp-logseq", "mcp-logseq"],
      "env": { "LOGSEQ_API_TOKEN": "your_token_here" }
    }
  }
}

Common uv locations:

• Curl install: ~/.local/bin/uv
• Homebrew: /opt/homebrew/bin/uv
• Pip install: Check with which uv

Connection Issues

• ✅ Confirm LogSeq is running
• ✅ Verify API server is started (not just enabled)
• ✅ Check port 12315 is accessible
• ✅ Test with verification command above

---

👩‍💻 Development

For local development, testing, and contributing, see **DEVELOPMENT.md**.

---