MCP server for LogSeq

✨ できること

LogSeq のナレッジベースを AI を活用したワークスペースに変えましょう！この MCP サーバーを使うと、Claude が LogSeq のグラフをシームレスに操作できます。

🎯 実際の使用例

📊 インテリジェントなナレッジ管理

"Analyze all my project notes from the past month and create a status summary"
"Find pages mentioning 'machine learning' and create a study roadmap"
"Search for incomplete tasks across all my pages"

📝 コンテンツ作成の自動化

"Create a new page called 'Today's Standup' with my meeting notes"
"Add today's progress update to my existing project timeline page"  
"Create a weekly review page from my recent notes"

🔍 スマートな調査と分析

"Compare my notes on React vs Vue and highlight key differences"
"Find all references to 'customer feedback' and summarize themes"
"Create a knowledge map connecting related topics across pages"

🧠 セマンティック検索 (オプション。ベクトル検索のセットアップが必要です)

"Find everything I wrote about burnout, even if I didn't use that word"
"What notes relate to my thoughts on deep work?"
"Search across my Dutch and English notes for ideas about productivity"

🤝 会議とドキュメント作成のワークフロー

"Read my meeting notes and create individual task pages for each action item"
"Get my journal entries from this week and create a summary page"
"Search for 'Q4 planning' and organize all related content into a new overview page"

💡 主なメリット

• コンテキスト切り替えが不要：Claude が LogSeq のデータを直接操作します
• ワークフローを維持：コンテンツを手動でエクスポートしたり、コピーしたりする必要はありません
• インテリジェントな整理：AI を活用したページの作成、リンク、検索が可能です
• 生産性の向上：繰り返し発生するナレッジワークを自動化できます
• セマンティックベクトル検索 (オプション)：ローカルの Ollama またはホスト型の OpenAI 互換埋め込みモデルを使用し、意味からノートを検索できます
• DB モード対応 (オプトイン)：Logseq の DB モードのグラフで、クラスのプロパティを読み書きできます

---

🚀 クイックスタート

ステップ 1：LogSeq API を有効にする

1. Settings → Features → 「Enable HTTP APIs server」にチェックを入れます
2. LogSeq の API button (🔌) をクリック → 「Start server」
3. API トークンを生成：API パネル → 「Authorization tokens」 → 「Create new」

ステップ 2：MCP クライアントに追加する（インストール不要！）

Claude Code

claude mcp add mcp-logseq \
  --env LOGSEQ_API_TOKEN=your_token_here \
  --env LOGSEQ_API_URL=http://localhost:12315 \
  -- uv run --with mcp-logseq mcp-logseq

Claude Desktop

設定ファイルに追加します（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "mcp-logseq": {
      "command": "uv",
      "args": ["run", "--with", "mcp-logseq", "mcp-logseq"],
      "env": {
        "LOGSEQ_API_TOKEN": "your_token_here",
        "LOGSEQ_API_URL": "http://localhost:12315"
      }
    }
  }
}

Codex CLI

uv をインストールし、Logseq の HTTP API を実行した状態で（ステップ 1）、次の内容を ~/.codex/config.toml に追加します。

[mcp_servers.logseq]
command = "uv"
args = ["run", "--with", "mcp-logseq", "mcp-logseq"]

[mcp_servers.logseq.env]
LOGSEQ_API_TOKEN = "YOUR_LOGSEQ_TOKEN"
LOGSEQ_API_URL = "http://127.0.0.1:12315"

YOUR_LOGSEQ_TOKEN を Logseq のトークンに置き換えてください。Codex が uv を見つけられない場合は、ターミナルで which uv を実行し、command にフルパスを指定してください。トークンは他人に知られないようにしてください。

上記の API ベースアドレスを使用し、/mcp は付けないでください。Codex はこのアダプターを STDIO 経由で実行します。アダプターは Logseq の通常の HTTP API に接続します。

Codex を再起動し、新しいローカルタスクを開いて、次のように依頼してください。

Logseq を使ってジャーナルページの一覧を表示し、今日のジャーナルを読んでください。何も変更しないでください。

Logseq とその API サーバーは起動したままにしてください。Codex がアダプターを自動的に起動するため、トンネルや別のターミナルウィンドウは必要ありません。

ページ一覧の取得とジャーナルの取得について、Logseq の DB グラフでテスト済みです。この設定はローカルの Codex タスク向けであり、クラウドでホストされる ChatGPT Chat 向けではありません。

OpenCode

~/.config/opencode/opencode.json に追加します。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp-logseq": {
      "type": "local",
      "command": ["uv", "run", "--with", "mcp-logseq", "mcp-logseq"],
      "enabled": true,
      "environment": {
        "LOGSEQ_API_URL": "http://localhost:12315",
        "LOGSEQ_API_TOKEN": "your_token_here"
      }
    }
  }
}

ステップ 3：使い始めましょう！

"Please help me organize my LogSeq notes. Show me what pages I have."

---

🔬 ベクトル検索（オプション）

設定可能な埋め込みモデルを使って Logseq のグラフをセマンティック検索します。キーワードだけでなく意味からノートを見つけられます。ベクトル類似度と全文検索を組み合わせてすべてのページを検索し、言語をまたいだ検索にも対応します。

完全にローカルで埋め込みを行うには Ollama を使用します。また、OpenAI やその他の OpenAI 互換埋め込みエンドポイントも利用できます。どの設定でも LanceDB はローカルで動作します。ホスト型プロバイダーには、埋め込み処理の対象となるノートのテキストが送信されます。

→ セットアップガイドの全文：VECTOR_SEARCH.md

---

🛠️ 利用可能なツール

サーバーは、インテリジェントな Markdown 解析機能を備えた 17 個のツールと、オプションのベクトル検索ツール 3 個を提供します。

ツール	用途	使用例
list_pages	グラフを閲覧します。sort: "updated" / updated_since で最近更新されたページを見つけます	「今週変更したページはどれですか？」
get_page_content	ページの内容を読み取ります	「プロジェクトのメモを取得して」
create_page	構造化されたブロックを含む新しいページを追加します	「議題項目を含む会議メモのページを作成して」
update_page	ページを変更します（追記／置換モード）	「タスクリストを更新して」
delete_page	ページを削除します	「古い下書きページを削除して」
delete_block	UUID でブロックを削除します	「この特定のブロックを削除して」
update_block	UUID でブロックの内容を編集します	「この特定のブロックのテキストを更新して」
get_block	プロパティと子要素を含むブロックを UUID で読み取ります	「この特定のブロックを表示して」
search	グラフ全体からコンテンツを検索します	「『生産性のヒント』を検索して」
query	Logseq DSL クエリを実行します（raw datalog はサポートされていません）	「#project タグが付いたすべての TODO タスクを探して」
find_pages_by_property	プロパティでページを検索します	「status = active のすべてのページを探して」
get_pages_from_namespace	名前空間内のページを一覧表示します	「Customer/ 配下のすべてのページを表示して」
get_pages_tree_from_namespace	階層型の名前空間ビューを表示します	「Projects/ をツリーとして表示して」
rename_page	参照を更新しながらページ名を変更します	「'Old Name' を 'New Name' に変更して」
get_page_backlinks	そのページにリンクしているページを探します	「このページにリンクしているのはどれですか？」
insert_nested_block	子ブロック／兄弟ブロックを挿入します	「このタスクの下に子ブロックを追加して」
set_block_properties	ブロックに DB モードのクラスプロパティを設定します	「このブロックのステータスを active に設定して」(DB モードのみ)
vector_search ⚗️	意味に基づいてセマンティック検索します	「シャドーワークやユングに関するメモを探して」
sync_vector_db ⚗️	ベクトル DB をグラフファイルと同期します	「検索インデックスを更新して」
vector_db_status ⚗️	ベクトル DB の状態と古さを表示します	「検索インデックスは最新ですか？」

⚗️ ベクトル検索のセットアップが必要です。VECTOR_SEARCH.md を参照してください。

🎨 スマート Markdown 解析（v1.1.0+）

create_page ツールと update_page ツールは、Markdown を Logseq ネイティブのブロック構造に自動変換するようになりました。

Markdown 入力：

---
tags: [project, active]
priority: high
---

# Project Overview
Introduction paragraph here.

## Tasks
- Task 1
  - Subtask A
  - Subtask B
- Task 2

## Code Example
```python
def hello():
    print("Hello Logseq!")
```

結果： 次の内容を含む、適切にネストされたブロックが作成されます。

• ✅ YAML フロントマターからページプロパティを取得（tags、priority）
• ✅ 見出し（#、##、###）から階層構造のセクションを作成
• ✅ 適切なインデントを持つネストされた箇条書き
• ✅ コードブロックを単一のブロックとして保持
• ✅ チェックボックスをサポート（- [ ] → TODO、- [x] → DONE）

更新モード：

• append（デフォルト）：既存のブロックの後に新しいコンテンツを追加します
• replace：ページをクリアし、新しいコンテンツに置き換えます

🔁 安全な再試行と大容量書き込み

同じタイトルのページがすでに存在する場合、create_page は明確なエラーを返します。Logseq が番号付きの重複（Page(1)、Page 2 など）を暗黙に作成することはありません。これにより、タイムアウト後も安全に再試行できます。以前の create_page 呼び出しがタイムアウトしたものの実際にはコミットされていた場合、再試行時には、コンテンツが孤立したページに分散することなく、ページがすでに存在することが通知されます。

大容量の書き込みでは、巨大な create_page 呼び出しを一度行うより、次のパターンをおすすめします。

1. コンテンツをほとんど、またはまったく含めずにページを作成します（タイトルとプロパティのみを指定して create_page を実行します）
2. update_page（mode: append）で、コンテンツを小さなチャンクに分けて追記します
3. get_page_content で読み戻し、結果を確認します

取り込みの途中で「すでに存在します」というエラーが発生した場合は、get_page_content で取り込まれた内容を確認し、再作成するのではなく update_page で続行してください。

---

⚙️ 前提条件

LogSeq のセットアップ

• LogSeq がインストールされ、実行中であること
• HTTP API サーバーが有効になっていること（Settings → Features）
• API サーバーが起動していること（🔌 ボタン → "Start server"）
• API トークンが生成されていること（API パネル → Authorization tokens）

システム要件

• uv Python パッケージマネージャー
• MCP 互換クライアント（Claude Code、Claude Desktop など）

---

🔧 設定

環境変数

• LOGSEQ_API_TOKEN（必須）：LogSeq API トークン
• LOGSEQ_API_URL（任意）：サーバー URL（デフォルト：http://localhost:12315）
• LOGSEQ_VERIFY_SSL（任意）：https:// の LOGSEQ_API_URL の TLS 証明書を検証するかどうかです。URL が https:// の場合はデフォルトで検証します。自己署名証明書の場合は、検証をスキップするために 0、false、または no を設定してください。それ以外の値を設定すると検証が有効になります。
• LOGSEQ_API_CONNECT_TIMEOUT（任意）：HTTP 接続タイムアウト（秒）（デフォルト：3）
• LOGSEQ_API_READ_TIMEOUT（任意）：HTTP 読み取りタイムアウト（秒）（デフォルト：6）
• LOGSEQ_LOG_LEVEL（任意）：ログの詳細度 — DEBUG、INFO、WARNING、ERROR、または CRITICAL（デフォルト：INFO）。ログは標準エラー出力に出力されます。DEBUG の場合、リクエストのペイロード全体が記録されないよう、MCP SDK 自体のロガーは INFO に制限されます。
• LOGSEQ_LOG_FILE（任意）：ログファイルのパス。設定されていない場合（デフォルト）、ディスクには何も書き込まれません。ツール呼び出しは引数名と結果のサイズのみを記録するため、ページやブロックの内容が通常のログに含まれることはありません。
• LOGSEQ_DB_MODE（任意）：DB モードのプロパティサポートを有効にするには true を設定します。Logseq の DB モードのグラフでのみ使用できます（ベータ版）。Markdown／ファイルベースのグラフを使用する場合は、設定しないでください。
• LOGSEQ_EXCLUDE_TAGS（任意）：カンマ区切りのタグ — これらのタグが付いたページは、すべてのツールから非表示になります。詳しくは、以下のプライバシーとアクセス制御をご覧ください。
• LOGSEQ_INCLUDE_NAMESPACES（任意）：カンマ区切りの名前空間許可リスト（例：work,projects）。設定すると、これらの名前空間内のページとそのサブページのみアクセス可能になり、名前空間のないトップレベルページを含むほかのすべてのページは、一覧表示と検索で非表示になり、直接アクセスも拒否されます。詳しくは、以下のプライバシーとアクセス制御をご覧ください。
• LOGSEQ_EXCLUDE_NAMESPACES（任意）：カンマ区切りの名前空間拒否リスト（例：finance,work/secret）。これらの名前空間は常にブロックされ、許可リストよりも優先されます。詳しくは、以下のプライバシーとアクセス制御をご覧ください。
• LOGSEQ_WRITE_NAMESPACES（任意）：カンマ区切りの書き込み許可リスト（例：Beren）。設定すると、書き込みツールの対象にできるのはこれらの名前空間内のページのみです。ほかのページは読み取り可能なまま、読み取り専用になります。この設定は、許可／拒否ルールに加えて適用され、それらのルールに代わるものではありません。詳しくは、以下のプライバシーとアクセス制御をご覧ください。
• LOGSEQ_CONFIG_FILE（任意）：グラフのパス、ACL のデフォルト設定、および vector ブロックを含む共有 JSON 設定ファイルのパス。環境変数（LOGSEQ_EXCLUDE_TAGS、LOGSEQ_INCLUDE_NAMESPACES、LOGSEQ_EXCLUDE_NAMESPACES、LOGSEQ_WRITE_NAMESPACES）は、このファイルの対応するキーより優先されます。
• MCP_HTTP_AUTH_TOKEN（--transport http で必須）：クライアントが Authorization: Bearer <token> として送信する必要があるベアラートークン。このトークンがない場合、サーバーは HTTP モードでの起動を拒否します。詳しくはHTTP での提供をご覧ください。

プライバシーとアクセス制御

除外タグが付いたページは AI から完全に隠されます。一覧表示、検索、クエリに表示されず、直接読み取ろうとするとアクセス拒否エラーが返されます。

環境変数を使った簡単な設定：

LOGSEQ_EXCLUDE_TAGS=private,secret

設定ファイルを使った設定（ベクトル検索にも使用）：

{
  "logseq_graph_path": "/path/to/your/logseq/pages",
  "exclude_tags": ["private", "secret"]
}

LOGSEQ_CONFIG_FILE=/path/to/config.json を指定してください。

Logseq のページで、保護したいページにタグを付けます：

tags:: private

除外設定はすべてのツール（list_pages、get_page_content、search、query、およびオプションのベクトル検索）に適用されます。ベクトル検索も使用する場合、ルートの exclude_tags はベクトルインデックスの除外リストに自動的に統合されるため、プライベートなページが埋め込み対象になることはありません。

名前空間のアクセス制御

LOGSEQ_INCLUDE_NAMESPACES と LOGSEQ_EXCLUDE_NAMESPACES を使用して、特定の名前空間へのアクセスを制限できます。

包含リスト（厳密な許可リスト）： リストに記載された名前空間とそのサブページのみが表示され、それ以外はすべて非表示になります。

LOGSEQ_INCLUDE_NAMESPACES=work,projects

除外リスト（拒否リスト）： リストに記載された名前空間は、包含リストに含まれていても常にブロックされます。

LOGSEQ_EXCLUDE_NAMESPACES=work/secret,finance

設定ファイルを使用する場合：

{
  "include_namespaces": ["work", "projects"],
  "exclude_namespaces": ["work/secret", "finance"],
  "write_namespaces": ["work/drafts"]
}

書き込みリスト（書き込み許可リスト）： 読み取りルールで許可されるすべての内容は引き続き読み取り可能ですが、書き込みツール（create_page、update_page、delete_page、rename_page、update_block、delete_block、insert_nested_block、set_block_properties）の対象にできるのは、これらの名前空間に属するページのみです。アシスタントに編集可能な範囲より広い領域を読み取らせる場合に便利です。

LOGSEQ_INCLUDE_NAMESPACES=Family,Beren
LOGSEQ_WRITE_NAMESPACES=Beren   # reads Family/* and Beren/*, writes only Beren/*

rename_page では、旧名と新名の両方が書き込みリストに含まれている必要があります。ブロックツールは、そのブロックの所有ページを基準にチェックされます（ページを特定できない場合は拒否されます）。リスト外への書き込みは「page 'X' is read-only for this assistant」を返します。書き込みリストによって読み取りアクセスの範囲が広がることはありません。包含リストで許可されていない書き込み名前空間へのアクセスは引き続き拒否されます（起動時に警告がログに記録されます）。未設定の場合、追加の制限はありません。許可された書き込みはすべて、Write: tool=<name> page=<page name> として INFO レベルでログに記録されます（名前のみで、内容は記録されません）。

照合はセグメント単位で、大文字と小文字を区別しません。work は work と work/projects に一致しますが、workshop には一致しません。動作は LOGSEQ_EXCLUDE_TAGS と同様です。リストや検索の結果ではブロックされたページは通知なく除外され、直接の読み取り、書き込み、削除、ブロック操作ではアクセス拒否エラーが返されます。

アクセス制御はページ単位で適用され、すべてのツールに適用されます。リスト、検索、クエリの結果からブロックされたページが除外され、ページやブロックへの直接アクセスとバックリンクは拒否され、ベクトル検索もフィルタリングされます。search と query で得られたブロック単位の結果は所有ページに紐付けて判定されるため、制限されたページに属するブロックも結果から除外されます。

インデックス作成時の名前空間のスコープ設定（ベクトル DB のみ）。 上記のキーはクエリ時に適用されます。すべてのページが埋め込まれ、ブロックされたページは各応答から除外されます。ベクトル DB では、設定ファイルの vector ブロック内にある include_namespaces / exclude_namespaces を使用して、インデックス作成時にスコープを設定することもできます。つまり、どの名前空間を DB に埋め込むかをあらかじめ決められます。

{
  "vector": {
    "enabled": true,
    "include_namespaces": ["work"],
    "exclude_namespaces": ["work/secret"]
  }
}

これはグローバル設定であり、すべての利用者が共有する DB の内容を決定します。また、読み取り時にフィルタリングするのではなく、不要な内容をディスクに保存しないようにします。埋め込みたくない機密情報がある場合や、全員が一部の範囲だけを必要とする場合にインデックスを小さく保つのに便利です。照合ルールは同じく、セグメント単位で大文字と小文字を区別しません。インデックスの内容が変わるため、変更を反映するにはインデックスを全面的に再構築する必要があります：logseq-sync --rebuild。

🌐 HTTP 経由での提供、マルチプロフィール、TLS

デフォルトでは、サーバーはstdioで通信します。クライアントがサブプロセスとしてサーバーを起動するため、ほとんどのユーザーは特別な設定を必要としません。ネットワーク経由でサンドボックス化されたクライアントやリモートクライアントに提供する場合、mcp-logseq はベアラー認証、プロフィールごとの分離、TLS に対応した、長時間稼働する HTTP サービスとして実行できます。

mcp-logseq --transport http --host 127.0.0.1 --port 12320   # requires MCP_HTTP_AUTH_TOKEN

サーバー側のセキュリティモデル、プロフィールごとのマルチインスタンスパターン、別個の書き込み用**logseq-sync、ネイティブのTLS**およびリバースプロキシの設定を含む、完全なデプロイガイドは docs/SERVING.md にあります。TLS を設定するか --insecure を指定しない限り、ループバック以外のアドレスへのプレーン HTTP バインドは拒否されます。

代替の設定方法

.env ファイルを使用する

# .env
LOGSEQ_API_TOKEN=your_token_here
LOGSEQ_API_URL=http://localhost:12315

システム環境変数

export LOGSEQ_API_TOKEN=your_token_here
export LOGSEQ_API_URL=http://localhost:12315

---

🔍 検証とテスト

LogSeq 接続のテスト

uv run --with mcp-logseq python -c "
from mcp_logseq.logseq import LogSeq
api = LogSeq(api_key='your_token')
print(f'Connected! Found {len(api.list_pages())} pages')
"

MCP 登録の確認

claude mcp list  # Should show mcp-logseq

MCP Inspector でのデバッグ

npx @modelcontextprotocol/inspector uv run --with mcp-logseq mcp-logseq

---

🐛 トラブルシューティング

よくある問題

「LOGSEQ_API_TOKEN environment variable required」

• ✅ Settings → Features で HTTP API を有効にします
• ✅ LogSeq の 🔌ボタン → 「Start server」 をクリックします
• ✅ API panel → Authorization tokens でトークンを生成します
• ✅ 設定でトークンを確認します

「spawn uv ENOENT」（Claude Desktop）

Claude Desktop が uv を見つけられません。フルパスを使用してください：

which uv  # Find your uv location

フルパスを指定して設定を更新します：

{
  "mcpServers": {
    "mcp-logseq": {
      "command": "/Users/username/.local/bin/uv",
      "args": ["run", "--with", "mcp-logseq", "mcp-logseq"],
      "env": { "LOGSEQ_API_TOKEN": "your_token_here" }
    }
  }
}

一般的な uv の場所：

• Curl でインストールした場合：~/.local/bin/uv
• Homebrew：/opt/homebrew/bin/uv
• Pip でインストールした場合：which uv で確認します

接続の問題

• ✅ LogSeq が実行中であることを確認します
• ✅ API サーバーが起動済みであることを確認します（有効化しただけではありません）
• ✅ ポート 12315 にアクセスできることを確認します
• ✅ 上記の確認コマンドでテストします

---

👩‍💻 開発

ローカルでの開発、テスト、コントリビューションについては、DEVELOPMENT.md を参照してください。

---