Logseq MCP Server

A Model Context Protocol server that gives an LLM configurable, safety-scoped access to a Logseq graph: query and search broadly (all output filtered by a blacklist), but write only inside the agent's own namespace plus a narrow task-status channel.

Built on FastMCP (the high-level API of the official mcp package).

Targets the file/Markdown ("OG") version of Logseq. The newer DB (SQLite) version changed the underlying schema; some methods may behave differently there.

Requirements

• A running Logseq with the local HTTP API server enabled (Settings → Features → HTTP APIs server, then start it from the 🔌 menu).
• An authorization token created in the HTTP API server settings.

Usage with Claude Desktop

{
  "mcpServers": {
    "logseq": {
      "command": "uvx",
      "args": ["mcp-server-logseq"],
      "env": {
        "LOGSEQ_API_TOKEN": "<YOUR_TOKEN>",
        "LOGSEQ_API_URL": "http://127.0.0.1:12315"
      }
    }
  }
}

Configuration

Source	Token	URL
Environment	LOGSEQ_API_TOKEN	LOGSEQ_API_URL (default http://localhost:12315)
CLI flag	--api-key	--url

The token is read from the environment or --api-key; it is never stored in code. A .env file is supported (see .env.example).

Config file (optional)

Behaviour beyond the defaults is set in a TOML file — path from LOGSEQ_MCP_CONFIG (default ~/.config/logseq-mcp/config.toml). Custom queries live in EDN files next to it. The server runs fine with no config file (safe read-mostly defaults); see examples/config.toml for a full annotated example.

Section	Key options
[read]	resolve_depth — how deep to expand ((block refs))
[write]	agent_write_prefix (default byAgent), allow_agents_write_any
[search]	files_path — graph folder; set it to use the ripgrep backend
[blacklist]	pages — pages (and subpages) to hide and redact everywhere
[tasks]	allow_status_change — gate for set_task_status
[audit_log]	enabled — log writes to today's journal
[queries.<name>]	a named query: file/inline query, register_as_tool, …

Secrets and the API URL stay in the environment, never in this file.

Transports

By default the server runs over stdio (for Claude Desktop and other local clients). A Streamable HTTP transport is also available for remote/networked use (e.g. a phone client):

LOGSEQ_MCP_HTTP_TOKEN=<client-secret> \
  mcp-server-logseq --transport streamable-http --host 0.0.0.0 --port 8000
# MCP endpoint: http://<host>:8000/mcp

Env vars: LOGSEQ_MCP_TRANSPORT, LOGSEQ_MCP_HOST, LOGSEQ_MCP_PORT, LOGSEQ_MCP_HTTP_TOKEN (or --http-token).

Authentication

The Streamable HTTP transport requires a bearer token: every request must send Authorization: Bearer <LOGSEQ_MCP_HTTP_TOKEN>, or it gets 401. The server refuses to start in this mode without a token set. Note this is a distinct secret from LOGSEQ_API_TOKEN:

Secret	Direction
LOGSEQ_API_TOKEN	this server → Logseq
LOGSEQ_MCP_HTTP_TOKEN	client (phone) → this server

⚠️ A bearer token over plain HTTP is only safe on an already-encrypted channel. Don't expose the raw port to the open internet. The easy path for a home/headless host is Tailscale: install it on the host and the client, and reach http://<host>.<tailnet>.ts.net:8000/mcp over the encrypted tunnel — no domains, nginx, or certificates. (tailscale serve can add TLS if you want https://.)

Docker

Build once:

docker build -t logseq-mcp .

Quick t

... View full README on GitHub