mcp-logseq

🚀 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:

| Tool | Purpose | Example Use | |------|---------|-------------| | list_pages | Browse your graph | "Show me all my pages" | | get_page_content | Read page content | "Get my project notes" | | create_page | Add new pages with structured blocks | "Create a meeting notes page with agenda items" | | update_page | Modify pages (append/replace modes) | "Update my task list" | | delete_page | Remove pages | "Delete the old draft page" | | delete_block | Remove a block by UUID | "Delete this specific block" | | update_block | Edit block content by UUID | "Update this specific block text" | | search | Find content across graph | "Search for 'productivity tips'" | | query | Execute Logseq DSL queries | "Find all TODO tasks tagged #project" | | find_pages_by_property | Search pages by property | "Find all pages with status = active" | | get_pages_from_namespace | List pages in a namespace | "Show all pages under Customer/" | | get_pages_tree_from_namespace | Hierarchical namespace view | "Show Projects/ as a tree" | | rename_page | Rename with reference updates | "Rename 'Old Name' to 'New Name'" | | get_page_backlinks | Find pages linking to a page | "What links to this page?" | | insert_nested_block | Insert child/sibling blocks | "Add a child block under this task" | | set_block_properties | Set DB-mode class properties on a block | "Set the status of this block to active" (DB-mode only) | | vector_search ⚗️ | Semantic search by meaning | "Find notes about shadow work or Jung" | | sync_vector_db ⚗️ | Sync vector DB with graph files | "Update the search index" | | vector_db_status ⚗️ | Show vector DB health and staleness | "Is my search index up to date?" |

⚗️ 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

---

## ⚙️ 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](https://docs.astral.sh/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](#-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:**
```bash
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