Skip to main content
Glama

mcp-logseq

Python stdio MCP server for the Logseq local HTTP API.

Requirements

  • Python 3.11+

  • Logseq desktop with the HTTP API enabled

  • A Logseq API token

In Logseq, enable the HTTP API from settings and copy the token. The server calls Logseq at http://127.0.0.1:12315/api by default.

Related MCP server: Logseq MCP Tools

Install

python -m venv .venv
.venv/bin/pip install -e ".[dev]"

Configure in Codex

From this project directory, install the package and add the stdio MCP server to Codex:

python -m venv .venv
.venv/bin/pip install -e .
codex mcp add logseq \
  --env LOGSEQ_API_TOKEN=your-token \
  --env LOGSEQ_API_URL=http://127.0.0.1:12315/api \
  -- "$(pwd)/.venv/bin/mcp-logseq"

On Windows PowerShell, use the virtualenv executable under .venv\Scripts:

py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
codex mcp add logseq `
  --env LOGSEQ_API_TOKEN=your-token `
  --env LOGSEQ_API_URL=http://127.0.0.1:12315/api `
  -- "$((Get-Location).Path)\.venv\Scripts\mcp-logseq.exe"

Replace your-token with the token from Logseq. After adding it, restart Codex so the new MCP server is loaded.

If you prefer to edit the config manually, generate the JSON form from this checkout:

.venv/bin/mcp-logseq --print-config

On Windows:

.\.venv\Scripts\mcp-logseq.exe --print-config

The server is stdio-only for MCP clients. The LOGSEQ_API_URL value is the local Logseq HTTP API that this stdio server calls behind the scenes.

Logseq Setup

  1. Open Logseq desktop.

  2. Enable the HTTP API in Logseq settings.

  3. Copy the API token.

  4. Use that token as LOGSEQ_API_TOKEN in the codex mcp add command.

  5. Keep Logseq running while using the MCP server.

Run

LOGSEQ_API_TOKEN=your-token mcp-logseq

On Windows PowerShell:

$env:LOGSEQ_API_TOKEN = "your-token"
.\.venv\Scripts\mcp-logseq.exe

The server uses stdio transport by default. Do not run it behind an HTTP server for MCP clients that expect stdio.

Optional environment variables:

  • LOGSEQ_API_URL: full API URL, default http://127.0.0.1:12315/api

  • LOGSEQ_TIMEOUT: request timeout in seconds, default 15

Test

Run the full local test suite:

.venv/bin/python -m pytest

On Windows:

.\.venv\Scripts\python.exe -m pytest

The suite covers the Logseq HTTP client, environment loading, MCP config generation, stdio startup, and every exported server tool's Logseq API method/argument mapping.

MCP Client Config

Generate a ready-to-copy config from this checkout:

.venv/bin/mcp-logseq --print-config

On Windows:

.\.venv\Scripts\mcp-logseq.exe --print-config

Then paste the JSON into your MCP client's config. A static example is also available in mcp.example.json.

{
  "mcpServers": {
    "logseq": {
      "command": "/absolute/path/to/mcp-logseq/.venv/bin/mcp-logseq",
      "args": [],
      "env": {
        "LOGSEQ_API_TOKEN": "your-token",
        "LOGSEQ_API_URL": "http://127.0.0.1:12315/api"
      }
    }
  }
}

Windows manual config example:

{
  "mcpServers": {
    "logseq": {
      "command": "C:\\Users\\you\\path\\to\\mcp-logseq\\.venv\\Scripts\\mcp-logseq.exe",
      "args": [],
      "env": {
        "LOGSEQ_API_TOKEN": "your-token",
        "LOGSEQ_API_URL": "http://127.0.0.1:12315/api"
      }
    }
  }
}

Tools

Generic:

  • logseq_call: call any Logseq API method by name.

App and graph:

  • get_current_graph

  • get_current_graph_configs

  • get_current_graph_favorites

  • get_current_graph_recent

  • get_current_graph_templates

  • get_user_configs

  • get_app_info

  • check_current_is_db_graph

Pages and blocks:

  • get_current_page

  • get_current_block

  • get_current_page_blocks_tree

  • get_all_pages

  • get_page

  • get_page_blocks_tree

  • get_page_linked_references

  • get_page_properties

  • get_pages_from_namespace

  • get_pages_tree_from_namespace

  • get_block

  • get_block_properties

  • get_block_property

  • get_previous_sibling_block

  • get_next_sibling_block

  • search

Queries:

  • query

  • datascript_query

Page editing:

  • create_page

  • create_journal_page

  • rename_page

  • delete_page

Block editing:

  • append_block_in_page

  • prepend_block_in_page

  • insert_block

  • insert_batch_block

  • move_block

  • update_block

  • remove_block

  • new_block_uuid

  • set_block_collapsed

  • set_block_icon

  • remove_block_icon

Properties and tags:

  • get_all_tags

  • get_all_properties

  • upsert_block_property

  • remove_block_property

  • upsert_property

  • remove_property

  • create_tag

  • get_tag

  • get_tags_by_name

  • get_tag_objects

  • add_block_tag

  • remove_block_tag

  • add_tag_extends

  • remove_tag_extends

  • add_tag_property

  • remove_tag_property

Assets and Git:

  • list_asset_files

  • make_asset_url

  • open_asset

  • git_exec

  • git_load_ignore_file

  • git_save_ignore_file

Tools that modify the graph are intentionally direct wrappers around Logseq's API. Use them with explicit page names, UUIDs, and content. Plugin callback/hook APIs are not exposed as first-class tools because a stdio MCP server cannot host interactive Logseq plugin callbacks; use logseq_call only for one-shot methods.

Available Tools

64 tools
add_block_tagC

Add a tag to a block.

Inputs: block_uuid (required), tag_id (required).

add_tag_extendsC

Make a tag extend another tag.

Inputs: tag_id (required), parent_tag_id_or_name (required).

add_tag_propertyC

Add a property to a tag.

Inputs: tag_id (required), property_id_or_name (required).

append_block_in_pageC

Append a block to a page.

Inputs: page_name (required), content (required), properties.

check_current_is_db_graphA

Return whether the current graph is a DB graph.

Inputs: no named parameters.

create_journal_pageC

Create a journal page for a date string accepted by Logseq.

Inputs: date (required).

create_pageC

Create a Logseq page.

Inputs: page_name (required), properties, redirect, journal, +3 more.

create_tagC

Create a tag.

Inputs: tag_name (required), uuid.

datascript_queryD

Run a Datascript query with optional inputs.

Inputs: datascript_query (required), inputs.

delete_pageB

Delete a Logseq page.

Inputs: page_name (required).

get_all_pagesB

Return all pages in the current graph, or in the provided repo.

Inputs: repo.

get_all_propertiesA

Return all properties in the current graph.

Inputs: no named parameters.

get_all_tagsA

Return all tags in the current graph.

Inputs: no named parameters.

get_app_infoB

Return Logseq app info, optionally for a specific key.

Inputs: key.

get_blockC

Fetch a block by UUID.

Inputs: block_uuid (required), include_children.

get_block_propertiesC

Fetch all properties for a block.

Inputs: block_uuid (required).

get_block_propertyC

Fetch one property for a block.

Inputs: block_uuid (required), key (required).

get_current_blockA

Return the current block being edited or selected in Logseq.

Inputs: no named parameters.

get_current_graphB

Return metadata for the current Logseq graph.

Inputs: no named parameters.

get_current_graph_configsB

Return current graph config values. Pass keys to read specific config entries.

Inputs: keys.

get_current_graph_favoritesB

Return favorites for the current graph.

Inputs: no named parameters.

get_current_graph_recentB

Return recent pages for the current graph.

Inputs: no named parameters.

get_current_graph_templatesB

Return templates for the current graph.

Inputs: no named parameters.

get_current_pageA

Return the page currently open in Logseq.

Inputs: no named parameters.

get_current_page_blocks_treeB

Fetch the current page's block tree.

Inputs: no named parameters.

get_next_sibling_blockC

Fetch a block's next sibling.

Inputs: block_uuid (required).

get_pageB

Fetch a Logseq page by name or UUID.

Inputs: page_name (required), include_children.

get_page_blocks_treeC

Fetch a page's block tree by page name.

Inputs: page_name (required).

get_page_linked_referencesC

Fetch linked references for a page.

Inputs: page_name (required).

get_page_propertiesC

Fetch properties for a page.

Inputs: page_name (required).

get_pages_from_namespaceC

Fetch flattened pages from a namespace.

Inputs: namespace (required).

get_pages_tree_from_namespaceC

Fetch namespace pages as a tree.

Inputs: namespace (required).

get_previous_sibling_blockC

Fetch a block's previous sibling.

Inputs: block_uuid (required).

get_tagC

Fetch a tag by name or identity.

Inputs: name_or_ident (required).

get_tag_objectsC

Fetch objects tagged by a tag.

Inputs: name_or_ident (required).

get_tags_by_nameC

Fetch tags matching a name.

Inputs: tag_name (required).

get_user_configsB

Return Logseq user configuration.

Inputs: no named parameters.

git_execC

Run a Logseq Git command.

Inputs: args (required).

git_load_ignore_fileB

Load the current graph's Git ignore file.

Inputs: no named parameters.

git_save_ignore_fileC

Save the current graph's Git ignore file.

Inputs: content (required).

insert_batch_blockC

Insert multiple blocks under or near an existing block.

Inputs: target_block_uuid (required), batch (required), sibling, before, +1 more.

insert_blockC

Insert a block under or near an existing block.

Inputs: target_block_uuid (required), content (required), sibling, before, +4 more.

list_asset_filesA

List asset files in the current graph, optionally filtered by extension.

Inputs: exts.

logseq_callC

Call any Logseq API method, for example logseq.Editor.getCurrentPage.

Inputs: method (required), args.

make_asset_urlB

Create a Logseq asset URL for a graph-relative asset path.

Inputs: path (required).

move_blockC

Move a block relative to another block.

Inputs: source_block_uuid (required), target_block_uuid (required), before, children.

new_block_uuidA

Create a new UUID string suitable for a Logseq block.

Inputs: no named parameters.

open_assetC

Ask Logseq to open an asset path with its built-in opener.

Inputs: path (required).

prepend_block_in_pageC

Prepend a block to a page.

Inputs: page_name (required), content (required), properties.

queryC

Run a Logseq Datalog query with optional inputs.

Inputs: datalog_query (required), inputs.

remove_blockC

Remove a block by UUID.

Inputs: block_uuid (required).

remove_block_iconC

Remove a block icon.

Inputs: block_uuid (required).

remove_block_propertyC

Remove a block property.

Inputs: block_uuid (required), key (required).

remove_block_tagB

Remove a tag from a block.

Inputs: block_uuid (required), tag_id (required).

remove_propertyC

Remove a graph property.

Inputs: key (required).

remove_tag_extendsC

Remove a tag extension relationship.

Inputs: tag_id (required), parent_tag_id_or_name (required).

remove_tag_propertyC

Remove a property from a tag.

Inputs: tag_id (required), property_id_or_name (required).

rename_pageC

Rename a Logseq page.

Inputs: old_name (required), new_name (required).

set_block_collapsedA

Set a block collapsed flag. Use true, false, or 'toggle'.

Inputs: block_uuid (required), flag (required).

set_block_iconC

Set a block icon. icon_type is usually 'emoji' or 'tabler-icon'.

Inputs: block_uuid (required), icon_type (required), icon_name (required).

update_blockC

Update a block's content by UUID.

Inputs: block_uuid (required), content (required), properties.

upsert_block_propertyC

Create or update a block property.

Inputs: block_uuid (required), key (required), value (required).

upsert_propertyC

Create or update a graph property schema.

Inputs: key (required), schema, name.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 64 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, but there is some overlap between query/search/datascript_query and get_block_properties/get_block_property, which could cause misselection. Overall, descriptions help differentiate.

    Naming Consistency4/5

    The naming convention is largely consistent with verb_noun snake_case (e.g., get_block, create_page). However, a few outliers like check_current_is_db_graph, git_exec, and logseq_call deviate from the pattern, causing minor inconsistency.

    Tool Count2/5

    The 64 tools are excessive for typical MCP servers (usually 3-15). While Logseq has many features, this number may overwhelm agents, leading to poor selection and increased complexity.

    Completeness5/5

    The tool set covers nearly all aspects of Logseq: blocks, pages, tags, properties, graphs, configs, Git, assets, queries. There are no obvious gaps; users can perform full CRUD and lifecycle operations.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol server that enables AI agents to interact with local Logseq knowledge graphs, supporting operations like creating/editing pages and blocks, searching content, and managing journal entries.
      13
      15
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol server that enables AI agents to interact with a local Logseq instance, allowing operations like creating pages, managing blocks, and searching across a knowledge graph.
      13
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Exposes the mindgap knowledge graph as an MCP server over stdio, providing tools to add, link, query, and manage nodes and edges in a local org-roam-style graph.
      10
      MIT