Logseq API MCP Server

What is Logseq API MCP Server?

The Logseq API MCP Server bridges AI assistants (like Claude Desktop) with your local Logseq knowledge graph by exposing 21 MCP tools for reading, writing, querying, and searching notes. It is built for anyone who wants their AI to directly access and modify their Logseq graph — with optional privacy controls and automatic tool registration when you drop a Python file into src/tools/.

How to use Logseq API MCP Server?

Clone the repository, run uv sync, copy .env.template to .env, and set LOGSEQ_API_ENDPOINT (default http://127.0.0.1:12315/api) and LOGSEQ_API_TOKEN (obtain from Logseq Settings → Features → Developer mode). Then add the server to your Claude Desktop config (~/.claude/claude_desktop_config.json) with uv run --directory /path/to/logseq-api-mcp python src/server.py. Restart Claude Desktop; all 21 tools become available.

Key features of Logseq API MCP Server

• 21 tools: 12 read (search, query, page/block retrieval) and 10 write (create, edit, delete pages/blocks)
• Automatic tool discovery: drop a Python file into src/tools/ — no registration needed
• Privacy filter: pages tagged with tags from LOGSEQ_EXCLUDE_TAGS are hidden from all read operations
• DB‑mode support: set LOGSEQ_DB_MODE=true to enable database‑format API paths and Datalog‑powered queries
• Full‑text search across blocks, pages, and file names
• Backlink analysis including block‑level references

Use cases of Logseq API MCP Server

• Let an AI assistant search and retrieve your Logseq notes during a conversation
• Automate page and block creation, editing, or deletion from external tools
• Run raw Datalog queries against your graph for custom analysis
• Build a custom MCP tool and have it automatically registered alongside the built‑in ones
• Apply privacy exclusions to keep sensitive pages out of AI‑agent reach

FAQ from Logseq API MCP Server

What are the runtime dependencies?

Python 3.11 or higher and the uv package installer. The Logseq desktop app must be running with its HTTP API server enabled.

Where does my data live?

All data stays on your local Logseq instance. The MCP server connects to Logseq’s own HTTP API (http://127.0.0.1:12315/api by default) and never sends your graph to an external service.

How does the privacy filter work?

Set LOGSEQ_EXCLUDE_TAGS to a comma‑separated list of tags. Any page carrying one of those tags is hidden from all read operations (listing, search, query, backlinks, content retrieval). The filter applies at query time and takes effect immediately when the variable changes.

What is DB‑mode and when should I use it?

Logseq’s newer database format stores the graph in SQLite rather than markdown files. Set LOGSEQ_DB_MODE=true to enable tools like set_block_properties and Datalog‑powered queries. Tools that don’t apply in DB‑mode return a clear error message.

How do I add my own tools?

Create a Python file in src/tools/ following the _run(client, config, ...) pattern. No imports, registration, or config changes are needed — the discovery system picks it up automatically on the next server start. Function names starting with _ are not registered.