Logseq API MCP Server

logseq-api-mcp

あなたの AI アシスタントは、毎回のセッションをあなたの Logseq ナレッジグラフを知らない状態で開始します。logseq-api-mcp はそれを解決します。ノートを読み取り、書き込み、クエリし、検索するための 21 のツール — src/tools/ に Python ファイルを置いた瞬間に自動登録されます。

---

クイックスタート

ステップ 1 — インストール

git clone https://github.com/gustavo-meilus/logseq-api-mcp.git
cd logseq-api-mcp
uv sync

ステップ 2 — 設定

cp .env.template .env
# open .env and set LOGSEQ_API_ENDPOINT and LOGSEQ_API_TOKEN

トークンの取得方法: Logseq を開き、Settings → Features → Developer mode に移動し、HTTP APIs server を有効にして、表示されるトークンをコピーします。デフォルトのエンドポイントは http://127.0.0.1:12315/api です。

ステップ 3 — 接続

// ~/.claude/claude_desktop_config.json
{
  "mcpServers": {
    "logseq-api": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/logseq-api-mcp", "python", "src/server.py"],
      "env": {
        "LOGSEQ_API_ENDPOINT": "http://127.0.0.1:12315/api",
        "LOGSEQ_API_TOKEN": "your_token_here"
      }
    }
  }
}

Claude Desktop を再起動します。21 のツールすべてが有効になります。

---

ツール

読み取り（12 のツール）

ツール	機能
get_all_pages	ID、UUID、ジャーナルフラグ、名前空間を持つすべてのページ
get_page_blocks	ID、UUID、子ブロック数を持つ階層的なブロックツリー
get_page_links	対象ページにリンクしているページ
get_page_backlinks	ブロックレベルの参照を含む完全なバックリンク分析
get_block_content	プロパティと直接の子ブロックを含むブロックの詳細
get_all_page_content	ページ全体: プロパティ、ブロック、展開された DB 参照
get_linked_flashcards	ページおよびリンクされたすべてのページからの Q&A フラッシュカードのペア
search	ブロック、ページ、ファイル名を対象とした全文検索
query	グラフに対する生の Datalog / DSL クエリ
find_pages_by_property	プロパティキーと任意の値でページを絞り込み
get_pages_from_namespace	Logseq 名前空間配下のすべてのページ
get_pages_tree_from_namespace	名前空間ページのネストされたツリー

書き込み（10 のツール）

ツール	機能
create_page	任意のプロパティとフォーマットを指定してページを作成
delete_page	ページを完全に削除
rename_page	ページの名前を変更し、すべての参照を更新
update_page	既存のページにコンテンツを追加または置換
append_block_in_page	ページの末尾にブロックを追加
edit_block	UUID でブロックの内容を置換
update_block	UUID でブロックの内容を更新
insert_nested_block	別のブロックを基準に子ブロックまたは兄弟ブロックを挿入
delete_block	UUID でブロックを削除
set_block_properties	ブロックに構造化プロパティを設定（DB モードのみ）

---

設定

変数	デフォルト	説明
LOGSEQ_API_ENDPOINT	http://127.0.0.1:12315/api	Logseq HTTP API のベース URL
LOGSEQ_API_TOKEN	（必須）	Bearer 認証トークン
LOGSEQ_VERIFY_SSL	true	TLS 検証をスキップするには false に設定
LOGSEQ_DB_MODE	false	Logseq データベース形式の API パスを有効化
LOGSEQ_EXCLUDE_TAGS	（空）	カンマ区切りのタグ — いずれかのタグを持つページは非表示になります
LOGSEQ_LOG_LEVEL	WARNING	ログレベル: DEBUG、INFO、WARNING、ERROR

---

DBモード

Logseq の新しいデータベース形式では、グラフデータを Markdown ファイルではなく SQLite に保存します。LOGSEQ_DB_MODE=true を設定すると、set_block_properties、get_all_page_content での UUID 参照解決、および find_pages_by_property での Datalog によるクエリが利用可能になります。DB モードでは適用されないツールは、暗黙的に失敗するのではなく、明確なエラーを返します。

---

プライバシー

LOGSEQ_EXCLUDE_TAGS のいずれかのタグが付けられたページは、すべての読み取り操作から消えます。適用はクエリ時に実行されるため、変数を切り替えるとすぐに反映されます。

操作	ページが除外されている場合の動作
get_all_pages	除外されたページは一覧に表示されません
search	除外されたページとそのブロックが結果から除去されます
query	結果は除外されたページ名に対して後からフィルタリングされます
find_pages_by_property	結果は後からフィルタリングされます
get_page_backlinks	除外された参照元ページが削除されます
get_all_page_content	除外されたページに対して ❌ Access denied を返します

---

ツールの追加

src/tools/my_tool.py を作成します。インポート、登録、設定の変更は不要です。検出システムが次回のサーバー起動時にそれを認識します。

from typing import List
from mcp.types import TextContent
from src.client.logseq_client import LogseqClient
from src.client.config import LogseqConfig, load_config
from src.logging_setup import get_logger

_log = get_logger(__name__)

async def _run(
    client: LogseqClient, config: LogseqConfig, param: str
) -> List[TextContent]:
    try:
        _log.debug("%s called", __name__)
        result = await client.some_api_method(param)
        return [TextContent(type="text", text=str(result))]
    except Exception as exc:
        _log.error("exception in %s: %s", __name__, exc, exc_info=True)
        return [TextContent(type="text", text=f"❌ Error: {exc}")]

async def my_tool(param: str) -> List[TextContent]:
    """One-line description — this becomes the MCP tool description."""
    cfg = load_config()
    return await _run(LogseqClient(cfg), cfg, param)

_run(client, config, ...) パターンにより、tests/conftest.py の FakeLogseqClient を介してロジックをテスト可能に保ちます。_ で始まる関数名は登録されません。

---

開発

uv sync --dev                                                        # all deps
uv run --group test pytest tests/ -v                                 # test suite (345 tests)
uv run --group test pytest tests/ --cov=src --cov-fail-under=85      # coverage gate
uv run ruff check --fix && uv run ruff format                        # lint + format
uv run mypy src/ --ignore-missing-imports                            # type check
uv run bandit -r src/                                                # security scan
uv run mcp dev src/server.py                                         # MCP inspector

---

Star 履歴

---

ライセンス

MIT — LICENSE を参照してください。

---

Logseq と MCP コミュニティのために作りました。