Logseq MCP Server

Logseq MCP サーバー

Logseq のグラフを、AI エージェントのメモリおよびワークスペースに変えます。
安全な範囲に限定した書き込み、デイリージャーナルの監査証跡、ツールとして公開される検証済みクエリを備えた、Logseq 用の Model Context Protocol サーバーです。公式の mcp パッケージの高レベル API である FastMCP を基盤にしています。

Logseq の ファイル／Markdown（「OG」）版を対象としています。グラフがエージェントのメモリとして適している理由の一つは、プレーンテキストファイルにあります。git で同期でき、grep で検索でき、永続性があり、ロックインもありません。新しい DB（SQLite）版では基盤となるスキーマが変更されているため、一部のメソッドの動作が異なる場合があります。

理由

エージェントには永続的なメモリが必要です。そして、あなたはすでにグラフという形でそれを管理しています。足りないのは、信頼できるアクセス手段です。エージェントには幅広く読み取り、有用な書き込みをしてほしいものの、書き込むべきでないものには決して触れず、何をしたかを確認できるようにする必要があります。それを可能にするのが、次の3つの設計上の選択です。

• 名前空間を限定した書き込み。 エージェントが書き込めるのは、自分専用のプレフィックス（デフォルトでは byAgent/）の下だけです。加えて、タスクの TODO/DOING/DONE マーカーだけを変更できる、意図的に狭く制限した名前空間横断チャネルを1つ用意しています。ブラックリストに登録されたページは、すべての読み取りで非表示になり、内容が伏せられます。
• デイリージャーナルの監査証跡。 書き込みが成功するたびに、今日のジャーナルへ 22:30 [[byAgent]] wrote [[byAgent/readingList/...]] のような行が追記されます。エージェントの作業を確認することが、すでに行っている朝の日課の一部になります。
• ツールとしての検証済みクエリ。 設定から既知の正常な Datalog を名前付きツール（query_week_plan など）として提供します。これにより、エージェントが手作業で datascript を組み立てる必要がなくなり、より低コストなモデルでも信頼性を保てます。

使い方

私は、常時稼働している Mac mini でこのサーバーを使い、個人用のグラフに接続した Claude Code エージェントの小規模な群れを運用しています。

• 夜間のリサーチ。 スマートフォンからリーディングリストにリンクを追加しておくと、夜間にエージェントがその項目を取得し（status:: researching）、記事を読むか、リポジトリをシャロークローンして読み込み、ページに構造化された要約を書き込み、ステータスを read に変更します。
• 朝のブリーフィング。 08:30 に小型モデルが、夜間に読んだもの、週間計画の進捗、現在の NOW／DOING タスクをまとめた1ページのダッシュボードを作成し、プッシュ通知を1件送信します。
• みんなで使う1つのジャーナル。 人間のタスクとエージェントの監査記録が、同じデイリーノートに並んで記録されます。

リサーチエージェントが書き込むページのプロパティや要約、関連性は、グラフの他の部分へ直接つながります。

flowchart LR
    A[AI agents] -- MCP tools --> S[logseq-mcp]
    S -- HTTP API --> L[Logseq graph]
    S -. audit line per write .-> J[daily journal]
    Y((you)) --> L
    Y -- morning review --> J

要件

• ローカル HTTP API サーバーを有効にした状態で Logseq が起動していること
  （Settings → Features → HTTP APIs server を開き、🔌 メニューから起動します）。
• HTTP API サーバーの設定で作成した認証トークン。

使い方

Claude Code

ローカル（stdio）、環境変数からトークンを取得：

claude mcp add logseq --scope user --env LOGSEQ_API_TOKEN=<YOUR_TOKEN> -- uvx mcp-server-logseq

または、Streamable HTTP 経由でリモートインスタンスに接続します（スマートフォンやリモートセッションからヘッドレスホストへ接続する方法です。トランスポートを参照してください）。

claude mcp add logseq --scope user --transport http http://<host>:8000/mcp \
  --header "Authorization: Bearer <LOGSEQ_MCP_HTTP_TOKEN>"

Claude Desktop

{
  "mcpServers": {
    "logseq": {
      "command": "uvx",
      "args": ["mcp-server-logseq"],
      "env": {
        "LOGSEQ_API_TOKEN": "<YOUR_TOKEN>",
        "LOGSEQ_API_URL": "http://127.0.0.1:12315"
      }
    }
  }
}

設定

ソース	トークン	URL
環境変数	LOGSEQ_API_TOKEN	LOGSEQ_API_URL（デフォルトは http://localhost:12315）
CLI フラグ	--api-key	--url

トークンは環境変数または --api-key から読み込まれ、コードに保存されることはありません。.env ファイルもサポートされています（.env.example を参照）。

設定ファイル（任意）

デフォルト以外の動作は TOML ファイルで設定します。パスは LOGSEQ_MCP_CONFIG から指定します（デフォルトは ~/.config/logseq-mcp/config.toml）。カスタムクエリは同じ場所にある EDN ファイルに保存します。設定ファイルがなくてもサーバーは問題なく動作します（安全な読み取り中心のデフォルト設定です）。注釈付きの完全な例は examples/config.toml を参照してください。

セクション	主なオプション
[read]	resolve_depth — ((block refs)) を展開する深さ
[write]	agent_write_prefix（デフォルトは byAgent）、allow_agents_write_any
[search]	files_path — グラフのフォルダー。ripgrep バックエンドを使うには設定します
[blacklist]	pages — 全箇所で非表示にして内容を伏せるページ（およびサブページ）
[tasks]	allow_status_change — set_task_status の許可設定
[audit_log]	enabled — 今日のジャーナルへの書き込みを記録
[worklog]	enabled、namespace、root_block、exclude、agent_namespace、agent_exclude — 作業ログのチャネル
[queries.<name>]	名前付きクエリ：file／インラインの query、register_as_tool、…

シークレットと API URL は環境変数で管理し、このファイルには保存しません。

トランスポート

デフォルトでは、サーバーは stdio 経由で実行されます（Claude Desktop などのローカルクライアント向け）。リモート／ネットワーク経由での利用（例：スマートフォンのクライアント）には、Streamable HTTP トランスポートも利用できます。

LOGSEQ_MCP_HTTP_TOKEN=<client-secret> \
  mcp-server-logseq --transport streamable-http --host 0.0.0.0 --port 8000
# MCP endpoint: http://<host>:8000/mcp

環境変数：LOGSEQ_MCP_TRANSPORT、LOGSEQ_MCP_HOST、LOGSEQ_MCP_PORT、LOGSEQ_MCP_HTTP_TOKEN（または --http-token）。

認証

Streamable HTTP トランスポートでは、ベアラートークンが必須です。すべてのリクエストで Authorization: Bearer <LOGSEQ_MCP_HTTP_TOKEN> を送信する必要があり、送信しない場合は 401 が返されます。トークンが設定されていない場合、サーバーはこのモードでの起動を拒否します。これは LOGSEQ_API_TOKEN とは別のシークレットであることに注意してください。

シークレット	方向
LOGSEQ_API_TOKEN	このサーバー → Logseq
LOGSEQ_MCP_HTTP_TOKEN	クライアント（スマートフォン）→ このサーバー

⚠️ 平文 HTTP 経由でのベアラートークンの使用が安全なのは、すでに暗号化されたチャネル上に限られます。ポートをそのままインターネットに公開しないでください。自宅のヘッドレスホストで手軽に使うなら Tailscale がおすすめです。ホストとクライアントにインストールし、暗号化トンネル経由で http://<host>.<tailnet>.ts.net:8000/mcp に接続できます。ドメイン、nginx、証明書は不要です。必要であれば、tailscale serve で TLS を追加できます（https:// を使う場合）。

Docker

一度だけビルドします。

docker build -t logseq-mcp .

手早く試す場合（一時的な実行です。停止時に --rm でコンテナーが削除されます）。

docker run --rm -p 8000:8000 \
  -e LOGSEQ_API_TOKEN=<logseq-token> \
  -e LOGSEQ_MCP_HTTP_TOKEN=<client-secret> \
  -e TZ=Europe/Moscow \
  logseq-mcp

永続的にデプロイする場合（例：ヘッドレスの Mac mini）。一度実行すれば、再起動時に --restart によって再び起動します。

docker run -d --name logseq-mcp --restart unless-stopped -p 8000:8000 \
  -e LOGSEQ_API_TOKEN=<logseq-token> \
  -e LOGSEQ_MCP_HTTP_TOKEN=<client-secret> \
  -e TZ=Europe/Moscow \
  -e LOGSEQ_MCP_CONFIG=/cfg/config.toml \
  -v /path/to/config-dir:/cfg:ro \
  -v "/path/to/your/graph:/graph:ro" \
  logseq-mcp

• -v .../config-dir:/cfg — config.toml（および queries/、rules/）を格納するフォルダーです。ファイル検索を有効にするには、この中で files_path = "/graph" を設定します。デフォルト設定で実行する場合は、マウントと LOGSEQ_MCP_CONFIG のどちらも省略してください。
• -v .../graph:/graph — ファイル検索用の Logseq グラフフォルダー（読み取り専用）です。
• -e TZ=<zone> — 監査ログのタイムスタンプに使うローカル時刻です（イメージには tzdata が含まれています。設定しない場合、時刻は UTC になります）。

コンテナーはポート 8000 で Streamable HTTP を提供し、ホスト上で実行されている Logseq と通信します。Docker Desktop（macOS／Windows）では、デフォルトの LOGSEQ_API_URL=http://host.docker.internal:12315 がすでにホストを指しています。Linux では --add-host=host.docker.internal:host-gateway を追加するか、LOGSEQ_API_URL にホストの IP アドレスを設定してください。Logseq の HTTP API サーバーが実行中で、接続を受け付けていることを確認してください。

ツール

すべての読み取り出力はフラットな JSON 形式に正規化され、ブラックリストを通過します。読み取り時には ((block refs)) が損失なく解決されます（解決されたブロックの uuid／status は保持されるため、それらに基づいて操作できます）。結果はコンパクトな JSON で出力され、ブロックには存在するフィールドのみが含まれます。空のフィールドは省略され、raw_content は text と異なる場合にのみ含まれます。頻繁に更新されるジャーナルでは、インデント付きの全フィールド形式と比べて、データ量は 3 分の 1 になります。

検索

• search — ブロック内容を全文検索します（query、regex?、limit?、case_sensitive?、exclude_journals?）。files_path が設定されている場合は ripgrep を使用し、設定されていない場合は datascript で内容を照合します。
• find_tasks — markers?、tag?、under_tag?（子孫）、page?、priority?、limit? でタスクブロックを検索します。
• list_pages — 名前空間内のページ名を一覧表示します。prefix? で指定し、depth? で階層数を制限します。名前空間に属する子ページを検出します。子ページは親ページの read_page には表示されない独立したページです。ブロックの内容ではなく、構造のみを返します。
• custom_query — 設定済みのクエリを名前で実行します（name、inputs?）。
• list_custom_queries — 設定済みのクエリを一覧表示します。
• datascript_query — Datalog クエリをそのまま実行します（query、inputs?、rules?）。

ガイド

• get_logseq_guide — このグラフのクエリ実行／書き込みに関する正式なガイドを返します（小文字の名前、プレフィックスによる子孫の指定、マーカーとジャーナルの日付の型、タグと参照、読み取り／書き込みのスコープに関する、検証済みの Datalog の注意事項を含みます）。サーバーと同じ場所に配置された唯一の信頼できる情報源であり、エージェントが動作を再解釈して誤った解釈をするのを防ぎます。

読み取り

• read_page — ページを正規化されたブロックツリーとして読み取ります（page、depth?）。日付 YYYY-MM-DD を指定すると、グラフのタイトル形式にかかわらず、その日のジャーナルを読み取ります。存在しないページを指定した場合は、空のツリーではなくエラーになります。
• read_block — ブロックとその子ブロックを読み取ります（uuid、depth?）。

書き込み（エージェントの名前空間のみ）

• write_note — agent_write_prefix 以下のページを作成／追記／置換します（subpath、content?、mode?、properties?）。
• set_page_properties — ページのプロパティを設定／削除します（subpath、properties。値を null にすると削除されます）。
• edit_block — 1 つのブロックの内容を置換します（uuid、old_content、new_content）。書き込み前の読み取りが必須です。old_content がブロックの現在の内容と完全に一致しない場合、編集は拒否されます。エージェントの名前空間のみで使用できます。

タスク

• create_task — エージェントの名前空間にタスクブロックを作成します（title、agent、project?、marker?、priority?、tags?、plan_page?、blocks_on?、on_page?）。タスクを作成する唯一の方法です。write_note はタスクマーカーで始まる内容を拒否します。
• set_task_status — タスクのマーカーのみを変更します（uuid、status）。[tasks].allow_status_change によって制御されます。

Worklog（本日のジャーナル；[worklog].enabled）

作業を行うエージェントは、人間が手作業で記録するのと同じ形式で、作業の記録先であるジャーナルに記録できる必要があります。

#_worklog
  #_work/dynamo
    ((6a9eb940-758e-4966-a31d-f91e79c35f42))
      17:50 #_agents/claude/work-scout told how to update

• list_work_projects — ノートを記録できるプロジェクトの限定リストです（[worklog].namespace の直接の子から exclude を除いたもの）。
• list_agents — ノートに署名できる名前の限定リストです。形式は <runtime>/<name> で、エージェントレジストリ（[worklog].agent_namespace、既定値は _agents）のちょうど2階層下にある、あらゆるランタイムのページが対象です。新しいランタイム（_agents/codex/...）を追加するのに設定は不要です。
• add_journal_note — プロジェクトの下にある本日のジャーナルに HH:MM #<agent> <text> を追記します（text、work、agent、task?）。タスクが指定されている場合は、((ref)) の下にネストされます。
• get_worklog_setup_template — エージェントの指示ファイル（CLAUDE.md、AGENTS.md）に追加する、worklog セクションです。どのタスクに記録するか、いつステータスを変更するか、エントリをどのような形式にするかを定めています。ユーザーが設定を依頼した場合にのみ呼び出されます。「CLAUDE.md に worklog を追加して」のように、どのセッションでも依頼できます。テンプレートは worklog_setup.md です。

署名はグループ化の階層ではなく、ノート内に記載します。そうしないと、同じプロジェクトに記録する複数のエージェントが別々の並列サブツリーに分かれ、それぞれ独自の時系列を持つことになります。なお、サーバーは呼び出し元を認証できません。すべてのセッションが同じベアラートークンを提示するため、agent はリストに照らして検証される、正直さに基づく慣例であり、本人確認ではありません。タイプミスは検出できますが、なりすましは防げません。

このリストで保証できるのは、エージェントが自分自身を登録できないことです。それを担保するルールが2つあります。レジストリはエージェントの書き込みプレフィックスの外部に置かれるため、write_note ではレジストリ内にページを作成できません。サーバーは、レジストリが書き込みプレフィックス内に設定されている場合、起動を拒否します。また、ファイルが存在するページだけが対象です。どのノートに [[_agents/claude/x]] と書いても、Logseq は参照のみのページを作成しますが、それだけで名前が登録されてしまうおそれがあります。そのため、エージェントの登録には Logseq で手動でページを作成する必要があります。

各ヘッダーを再利用するのは、その階層で最後のブロックである間に限られます。つまり、ジャーナルの最上位ブロック内の root_block、ルート内のプロジェクトグループ、そのグループ内のタスクアンカーです。ジャーナルは時系列に並ぶため、ヘッダーをどこにあっても再利用すると、後から記録したノートがそこに追加されます。朝に作成したルートを再利用すると、夕方のノートが、それより前に記録された午後の行より上に表示されます。また、2つのエージェントが2つのプロジェクトに記録する場合、ノートはそのプロジェクトの以前のグループに追加され、別のプロジェクトの後の行より上に表示されます。ヘッダーの後に別の内容が追加されると、次のノートは新しいヘッダーを作成します。これにより、作業が入り混じるとヘッダーが重複する代わりに、1日の記録を実際に起きた順に並べられます。

これは agent_write_prefix の外部に書き込む唯一の手段であるため、対象を絞った契約と引き換えにパスの制限を緩めています。追記のみ、本日のジャーナルのみ、作成するすべてのものは root_block の下に置くこと、work は列挙値から指定すること、task は既存のタスクブロックであること、そして時刻はサーバーが記録すること（呼び出し元から時刻を渡せないため、再開したエージェントが覚えている時刻を記録することはできません）。タスクマーカーで始まるテキストは拒否されます。create_task を使用してください。

動的

• query_<name> — register_as_tool = true が設定された各クエリは、それぞれ独立したツールとして公開されます。

開発

git clone https://github.com/dailydaniel/logseq-mcp.git
cd logseq-mcp
cp .env.example .env   # fill in LOGSEQ_API_TOKEN
uv sync
uv run mcp-server-logseq

MCP Inspector で確認します。

npx @modelcontextprotocol/inspector uv --directory . run mcp-server-logseq

ライセンス

MIT