Logseq

You can extend Logseq with external AI tools by running an MCP server that exposes Logseq operations to AI clients and provides an embedded assistant interface. This server makes it easy to search, edit, and analyze your Logseq graph from other AI tools while keeping your data local to your environment.

How to use

You will run the MCP server locally and connect your MCP clients (for example Windsurf or Claude Desktop) to it. The server presents a set of tools that let you search pages, read and modify blocks, manage tasks, capture journal entries, and analyze your data. Two interfaces are available: the MCP server itself for external AI clients, and Lain, an embedded AI assistant you can use inside Logseq.

How to install

Prerequisites are required before you start. You need Node.js version 18 or newer and a Logseq desktop app with the HTTP API server enabled (Settings → Features → HTTP APIs server). Then install dependencies, build, and run the MCP server.

# Install dependencies
pnpm install

# Build all packages
pnpm build

Additional setup and configuration

The MCP server can be started with a token for API access. When using Windsurf or Claude Desktop, you typically provide an API URL and a token to authorize requests. Below is an example configuration you would use in the MCP client integration. Replace YOUR_API_TOKEN with your actual token.

{
  "mcpServers": {
    "logseq": {
      "command": "node",
      "args": ["/path/to/logseq-ai/packages/mcp-server/dist/index.js"],
      "env": {
        "LOGSEQ_API_URL": "http://localhost:12315",
        "LOGSEQ_API_TOKEN": "your-token"
      }
    }
  }
}

Starting and testing the server

Build and start the MCP server, then test basic operations such as listing pages, creating blocks, or querying the graph. The server exposes a rich set of tools to perform these actions from your external AI clients.

# Build (if not already built)
pnpm --filter @logseq-ai/mcp-server build

# Run (provide your API token)
LOGSEQ_API_TOKEN=your-token pnpm --filter @logseq-ai/mcp-server start

Available tools

search_logseq

Search across pages and blocks to find relevant content within your Logseq graph.

get_page

Retrieve a page's content as plain text for processing in external tools.

get_pages

Fetch multiple pages in a single call to improve efficiency when gathering data.

get_page_with_context

Get a page along with its backlinks and forward links to understand context.

list_pages

List all pages in the graph for discovery and navigation.

create_page

Create a new page, optionally with an initial block structure.

delete_page

Delete a specified page from the graph.

create_block

Create a single block within a page.

create_blocks

Create multiple blocks with hierarchical structure for efficiency.

update_block

Update an existing block's content.

delete_block

Delete a specific block.

query_logseq

Run a Datalog query against the graph to extract structured data.

update_page_properties

Update metadata or properties on an existing page.

get_current_graph

Retrieve high-level information about the current graph.

get_graph_stats

Obtain statistics about the graph, such as pages by type and orphaned pages.

find_missing_pages

Identify pages that are referenced but do not exist.

find_orphan_pages

Find pages with no incoming links.

find_pages_by_properties

Find pages that match specific property values.

find_related_pages

Discover backlinks and forward links related to a topic.

get_block_backlinks

Find blocks that reference a specific block.

get_today

Get today’s journal page or create it if missing.

append_to_today

Append content to today’s journal entry.

get_recent_journals

Retrieve recent journal entries with optional content.

get_tasks

Retrieve the current TODO/DOING tasks across the graph.

create_task

Create a new task with content and optional metadata like priority and deadline.

mark_task

Change the status of a single task.

mark_tasks

Change the status of multiple tasks in a single operation.

search_tasks

Search tasks by keyword and optional markers.

get_overdue_tasks

Get tasks that are overdue.

get_tasks_due_soon

Get tasks due within a given number of days.

get_task_stats

Retrieve statistics about tasks, including totals and by status.

set_task_priority

Set or change a task's priority.

set_task_deadline

Set or remove a task deadline.

set_task_scheduled

Set or update the scheduled date for a task.