# 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

```bash
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:

```bash
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`:

```powershell
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:

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

On Windows:

```powershell
.\.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

```bash
LOGSEQ_API_TOKEN=your-token mcp-logseq
```

On Windows PowerShell:

```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:

```bash
.venv/bin/python -m pytest
```

On Windows:

```powershell
.\.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:

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

On Windows:

```powershell
.\.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`.

```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:

```json
{
  "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.