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.

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.