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 or hosted OpenAI-compatible embeddings
• 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 configurable 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.

Use Ollama for fully local embeddings, OpenAI, or another OpenAI-compatible embeddings endpoint. LanceDB remains local in every configuration. Hosted providers receive the note text being embedded.

→ **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

🔁 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 `. 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

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.

Namespace access control

You can restrict access to specific namespaces using `LOGSEQ_INCLUDE_NAMESPACES` and `LOGSEQ_EXCLUDE_NAMESPACES`.

Include list (strict allow-list): Only the listed namespaces and their sub-pages are visible; everything else is hidden.

LOGSEQ_INCLUDE_NAMESPACES=work,projects

Exclude list (deny-list): The listed namespaces are always blocked, even if they appear in the include list.

LOGSEQ_EXCLUDE_NAMESPACES=work/secret,finance

Via config file:

{
  "include_namespaces": ["work", "projects"],
  "exclude_namespaces": ["work/secret", "finance"]
}

Matching is segment-based and case-insensitive: `work` matches `work` and `work/projects` but not `workshop`. The behavior mirrors `LOGSEQ_EXCLUDE_TAGS`: list/search results silently omit blocked pages; direct read, write, delete, and block operations return an access-denied error.

Access control is enforced at the page level and applied across every tool: list/search/query results omit blocked pages, direct page/block access and backlinks are denied, and vector search is filtered. Block-level results from `search` and `query` are resolved back to their owning page, so a block belonging to a restricted page is filtered out of those results too.

Index-time namespace scoping (vector DB only). The keys above are *query-time*: every page is embedded, and blocked ones are filtered out of each response. For the vector DB you can also scope at *index time* — decide which namespaces are embedded into the DB at all — with `include_namespaces` / `exclude_namespaces` inside the `vector` block of the config file:

{
  "vector": {
    "enabled": true,
    "include_namespaces": ["work"],
    "exclude_namespaces": ["work/secret"]
  }
}

This is global (it shapes the shared DB for every consumer), and it keeps unwanted content off disk entirely rather than filtering it on read — useful for secrets you never want embedded, or to keep the index small when everyone only cares about a subset. Matching is the same segment-based, case-insensitive rule. Because it changes what the index contains, it only takes effect after a full re-index: `logseq-sync --rebuild`.

🌐 Serving over HTTP, multi-profile & TLS

By default the server speaks stdio — your client spawns it as a subprocess, and most users need nothing more. To serve sandboxed or remote clients over the network, `mcp-logseq` can run as a long-lived HTTP service with bearer auth, per-profile isolation, and TLS:

mcp-logseq --transport http --host 127.0.0.1 --port 12320   # requires MCP_HTTP_AUTH_TOKEN

The full deployment guide — the server-side security model, the per-profile multi-instance pattern, the separate `logseq-sync` writer, and native TLS / reverse-proxy setup — lives in **docs/SERVING.md**. Non-loopback binds over plain HTTP are refused unless you supply TLS or pass `--insecure`.

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**.