コンテンツにスキップ
Oleaflyv0.4.12

接続

Claude Desktop、Claude Code、Cursor、Codex、またはほかの MCP クライアントを、Oleafly のローカルなプロジェクトツールに接続します。

Oleafly は MCP(Model Context Protocol)サーバーとして動作できます。Claude Desktop、Claude Code、Cursor、Codex、Grok CLI などの MCP クライアントから、Oleafly のプロジェクトを読み、編集し、検索し、コンパイルできます。モデルはクライアントが用意するので、Oleafly に AI プロバイダのキーを設定する必要はありません。

すでに Claude(または同様のもの)のサブスクリプションがあり、設定に API キーを貼り付けずに、そのチャットアプリから Oleafly を操作したい場合は、この方法を選びます。

双方向の MCP一方向では、Claude Desktop、Cursor、Codex などのお使いのコンピュータ上の MCP クライアントが、ベアラートークンを使って 127.0.0.1 の Oleafly の MCP サーバーに接続します。プロジェクトの読み取り、編集、コンパイルができ、どの変更をあなたの確認待ちにするかは承認ポリシーで決まります。もう一方向では、Oleafly 内蔵のアシスタントが、追加した MCP サーバーのツールを使います。コマンドを実行するローカルサーバーと、URL にあるリモートサーバーのどちらも使えます。MCP クライアントが Oleafly のツールを使うOleafly のアシスタントが他の MCP サーバーを使うMCP クライアントClaude Desktop,Cursor, CodexOleafly MCP127.0.0.1 のみプロジェクト読み書き・コンパイルベアラートークン承認アシスタントOleafly に内蔵ローカルサーバーコマンドを実行リモートサーバーURL に接続双方向の MCP一方向では、Claude Desktop、Cursor、Codex などのお使いのコンピュータ上の MCP クライアントが、ベアラートークンを使って 127.0.0.1 の Oleafly の MCP サーバーに接続します。プロジェクトの読み取り、編集、コンパイルができ、どの変更をあなたの確認待ちにするかは承認ポリシーで決まります。もう一方向では、Oleafly 内蔵のアシスタントが、追加した MCP サーバーのツールを使います。コマンドを実行するローカルサーバーと、URL にあるリモートサーバーのどちらも使えます。MCP クライアントが Oleafly を使うアシスタントがサーバーを使うMCP クライアントClaude Desktop, CursorOleafly MCP127.0.0.1 のみプロジェクト読み書き・コンパイルベアラートークン承認アシスタントOleafly に内蔵ローカルサーバーコマンドを実行リモートサーバーURL に接続
お使いのコンピュータ上の MCP クライアントは、127.0.0.1 とトークンを通じて Oleafly のプロジェクトツールを使います。逆方向では、Oleafly のアシスタントが、追加した MCP サーバーのツールを使えます。
  1. 設定 → 連携 → Oleafly MCP を開きます。
  2. MCP サーバーを有効にする をオンにします。

サーバーが動作するのは、Oleafly のプロセスが開いている間だけです。待ち受けるのは 127.0.0.1 だけで、ローカルネットワークで待ち受けることはありません。プロジェクトのウィンドウを閉じても、サーバーは止まりません。止まるのは、MCP をオフにしたとき、または Oleafly を終了したときです。

Oleafly はポート 5323(http://127.0.0.1:5323/mcp)を優先して使います。使えない場合、サーバーは空いている別のローカルポートに自動で割り当て、次回の起動用にそれを保存します。設定には、現在有効な URL が表示されます。再起動ボタンは、可能なら現在のポートを再利用し、そうでなければ空いている別のポートを選びます。

設定には、よく使われるクライアント向けの、コピーして貼り付けられるスニペットが表示されます。選ばれたポートが 5323 と異なる場合があるので、実際の URL をコピーし、<token> を設定のベアラートークン(表示 / コピー)に置き換えます。

ターミナルウィンドウ
claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"

claude_desktop_config.json に追加します(Desktop は stdio を優先するため、mcp-remote を使った stdio ブリッジです)。

{
"mcpServers": {
"oleafly": {
"command": "npx",
"args": [
"-y",
"mcp-remote@latest",
"http://127.0.0.1:5323/mcp",
"--header",
"Authorization: Bearer <token>",
"--transport",
"http-only"
]
}
}
}

各リリースには Claude Desktop の拡張機能 oleafly.mcpb が含まれているので、設定ファイルやトークンは不要です。最新リリース (新しいタブで開きます)からダウンロードし、Claude Desktop で開いてインストールしてください。

拡張機能はアプリに付属する oleafly コマンドを起動し、Oleafly で開いているプロジェクトを操作します。そのため、Oleafly を MCP サーバーをオンにしたまま起動しておいてください。Claude Desktop がコマンドを見つけられない場合は、拡張機能の設定で選択します。macOS では Oleafly.app/Contents/MacOS 内の oleafly-cli、Windows では %LOCALAPPDATA%\Oleafly 内の oleafly-cli.exe です。

MCP Registry には同じ拡張機能が io.github.Oleafly/oleafly として掲載されています。

.cursor/mcp.json(またはお使いのクライアントの MCP 設定)に、次の内容を記述します。

{
"mcpServers": {
"oleafly": {
"url": "http://127.0.0.1:5323/mcp",
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}

~/.grok/config.toml に、次の内容を記述します。

[mcp_servers.oleafly]
url = "http://127.0.0.1:5323/mcp"
headers = { Authorization = "Bearer <token>" }

Oleafly の設定にある Codex CLI のスニペットを使います。これは、実行中のサーバーへの stdio ブリッジを提供します。このエントリを Codex の設定に追加し、Oleafly が表示する実際の URL とトークンを使います。

~/.codex/config.toml
[mcp_servers.oleafly]
command = "npx"
args = [
"-y",
"mcp-remote@latest",
"http://127.0.0.1:5323/mcp",
"--header",
"Authorization: Bearer <token>",
"--transport",
"http-only"
]

このブリッジには Node.js と npx が必要です。設定を変更したら、クライアントを再起動するか、再接続します。

セットアップをスクリプト化したい場合は、Oleafly のデータの隣にある mcp.json ファイル(場所は設定に表示されます)に、同じ URL とトークンが入っています。このファイルは、サーバーが動作している間だけ書き込まれ(Unix ではモード 0600)、サーバーが止まると削除されます。ほかのローカルの秘密情報と同じように扱ってください。

ほとんどの MCP ツールは、アプリ内のアシスタントと名前とスキーマを共有しています。プロジェクトの検出とルーティングのツールは、デスクトップのバックエンドが提供します。

ツールは、アプリで開いているプロジェクトがあれば、それを対象にします。ウィンドウが接続されている場合は、list_projects と open_project で別のプロジェクトを選べます。

最後のウィンドウが閉じたあとも、バックエンドは read_file、list_files、search_project を使えるままにします。ネイティブの書き込み、置換、作成、名前の変更も、承認のポリシーが許す場合は使えます。これらのツールが使うのは、アプリが最後に報告したプロジェクトだけで、そのプロジェクトがもう有効でなければ、呼び出しを拒否します。ライブラリ内のほかのプロジェクトから推測することはありません。状態の確認、プロジェクトの選択、削除、コンパイル、ログ、PDF の確認、テーマの変更、図のツールには、接続されたウィンドウが必要です。

ツールできること
get_statusOleafly のバージョン、開いているプロジェクト、そのドキュメントエンジン、メイン文書、最後のコンパイルの状態、最後のコンパイルが失敗した、または実行できなかった理由
list_projectsID、名前、エンジン、種類、メイン文書、タイムスタンプ、色、プレビューの状態、書き出しの履歴を含むプロジェクトの一覧
open_projectID を指定してプロジェクトを開き、ほかのツールの対象にする
list_filesプロジェクトのファイルツリー
project_mapアウトライン、ラベル、引用、マクロ、入力グラフ、未解決の参照
search_project現在のプロジェクト内のテキストを検索する
ツールできること
read_fileプロジェクトのファイルを読む
get_log最後のコンパイルのログ
get_pdf_textコンパイルした PDF から抽出したテキスト
verify_pdf_pagesレンダリングした PDF のページにレイアウトの問題がないか、ページ画像またはページのテキストから確認する

get_pdf_text と verify_pdf_pages は、Oleafly にある最後の PDF を読み取ります。最後のコンパイルが失敗した、または実行できなかった場合、その結果には、PDF が古いことと、その理由が示されます。以前のコンパイルのものか、失敗したコンパイルの途中までのものだからです。get_log も、最後のコンパイルを実行できなかったときは同じように伝えます。そのログは以前のコンパイルのものだからです。

ツールできること
write_fileファイルを書き込む、または上書きする
replace_in_fileファイル内で検索して置換する
create_fileファイルまたはフォルダを作成する
rename_fileパスの名前を変更する、または移動する
delete_fileファイルまたはフォルダを削除する
set_main_docコンパイルの起点となる文書を設定する
ツールできること
compileプロジェクトを PDF にコンパイルする
preview_figure図だけを描画して、PNG 画像を返す
insert_figure最後にプレビューした図を文書に挿入する
load_image図の作業のために、プロジェクトの画像を読み込む

compile は、ビルドが成功したかどうかを伝え、そのエラーを一覧し、PDF があるかどうかを伝え、最後にログの末尾部分を付けます。終了したビルドでは、警告も報告します。ビルドを実行できなかった、終了しなかった、またはソースの外にあるもの(TeX のインストールや、ない Typst のバージョンなど)が必要な場合、結果には理由と、Oleafly がアプリであなたに示している対処法が書かれます。このツールは、クライアントに、あなたに伝えること、ソースには手を加えないことを求めます。あなたが止めたコンパイルは停止として記録されるので、クライアントがコードの誤りとして扱うことはありません。Oleafly 自身のアシスタントも、同じ結果を受け取ります。

まず get_status を呼び出して、プロジェクトが LaTeX、Typst、Markdown のどれかを確認し、その形式でソースを書きます。preview_figure と insert_figure は、LaTeX と Typst のプロジェクトで動作します。

  • LaTeX では、図は小さな単独の文書の中でコンパイルされる TikZ のコードで、insert_figure はそれを figure 環境で囲みます。
  • Typst では、図は CeTZ のキャンバスや fletcher のダイアグラムなどの Typst マークアップで、プロジェクトの Typst バージョンで描画されます。insert_figure はそれを #figure で囲み、ラベルをその後ろに置き、#import の行をその上に移します。
  • Markdown プロジェクトでは、どちらのツールもエラーを返し、何も変更しません。

load_image は、どのプロジェクトでも動作します。

ツールできること
toggle_themeライト / ダークモードを切り替える
ツールできること
list_skillsインストール済みのスキルを、ID、名前、説明、オンかどうかとともに一覧にする
load_skill1 つのスキルの指示の全文とファイル一覧を読み込む
read_skill_fileスキルのフォルダにある参考資料やスクリプトを読む

スキルのツールは、接続した直後から、プロジェクトを開いていなくても、Oleafly のウィンドウがなくても動作します。クライアントには、設定でオフにしたものも含め、有効なすべてのスキルが見えます。オン・オフのスイッチが決めるのは、Oleafly 自身のアシスタントが使うスキルであって、クライアントが読めるものではありません。代わりにフォルダからスキルを読むエージェントは 設定 → AI アシスタント → スキル の このコンピュータのほかのエージェントとスキルを共有 を使えます。スキルを参照してください。

これらのツールは、ノートをオンにするで説明しているとおり、設定 → 実験的な機能でノートがオンの間だけ使えます。開いているプロジェクトではなく、自分のノートに対して動作し、接続したウィンドウが必要です。

ツールできること
list_knowledge_notesノートを新しい順に、ID、タイトル、タグ、リンクしたプロジェクト、短い要約とともに一覧表示する。タグやプロジェクトで絞り込める
search_notesノートを検索し、ID、タイトル、タグ、リンク、一致したスニペットを返す
read_note_by_idノートを、フロントマター付きの Markdown として読み取る
today_note今日のデイリーノートを読み取る。まだなければ、付くはずのタイトルを返す
list_note_tasksノートのチェックボックス付きタスクを、新しいノート順に一覧表示する。ノートと、未完了か完了かで絞り込める
note_backlinksあるノートにリンクしているノートを、各リンクの前後のテキストとともに一覧表示する
append_to_noteノートまたは今日のデイリーノートの末尾に、Markdown を追加する
edit_note_sectionノートの 1 つの見出しの下の部分を書き直すか、その末尾に追加する
create_noteタイトル、Markdown、タグ、リンクするプロジェクトを指定して、ノートを作成する

append_to_note と edit_note_section は、ノートに直接は書き込みません。その変更は、Oleafly で承認するまで、提案としてノートに表示されます。create_note は Oleafly での承認を待ち、先に今日のデイリーノートを作る必要があるときの append_to_note も同様です。この接続を信頼するの設定では、ノートの作成で確認されません。共同編集サーバーで共有しているノートは、この方法では読めますが、変更はできません。読み取り専用にすると、ノートを変更する 3 つのツールがなくなります。

多くの MCP クライアントは、ツールを呼び出す前に確認します。Oleafly も 設定 → 連携 → Oleafly MCP で選んだポリシーを適用します。

  • すべての変更を確認する が既定です。アプリのウィンドウが接続されている間は、書き込み、名前の変更、削除で承認カードが表示されます。ウィンドウがない場合は、カードを表示する場所がないため、それらの操作は拒否されます。
  • 編集は自動承認、削除は確認 では、書き込みと名前の変更がバックエンドで実行されます。削除には、確認のために接続されたウィンドウが引き続き必要です。
  • この接続を信頼する では、バックエンドの書き込みと名前の変更が、Oleafly の確認なしで実行されます。削除には、接続されたウィンドウが引き続き必要です。このポリシーは、クライアントとそのクライアント自身の承認の仕組みを信頼できる場合にだけ使ってください。

さらに 2 つのスイッチが、これを補強します。

  • 読み取り専用 は別のトグルです。変更を伴うツールを tools/list から完全に取り除くので、上のポリシーがどうであれ、外部のアプリは読み取りとコンパイルはできても、ファイルを変更することはできません。
  • ベアラートークン: ~/.oleafly/ 以下の、認証付きで暗号化されたローカルストレージに保存される、256 ビットのランダムな値です。再発行すると、古いクライアントが無効になります。一般的な設定の読み取りで、トークンが公開されることはありません。設定でトークンを表示できるのは、実行中のサーバーの接続用コントロールだけです。

そして、設定できない不変条件が 2 つあります。

  • ローカルホストのみ: バインドするアドレスは 127.0.0.1 です。ブラウザの Origin ヘッダーを持つリクエストは拒否され、Host はループバックでなければなりません。
  • プロジェクトへの閉じ込め: バックエンドのファイルツールは、プロジェクトからの相対パスを受け付け、正規化したパスを、アプリが報告したプロジェクトの範囲に閉じ込めます。ツールの呼び出しで、別のプロジェクト ID を渡したり、バックエンドにライブラリ内の別のプロジェクトを選ばせたりすることはできません。

ウィンドウが接続されている間は MCP の動作状況 タブに、受け付けた呼び出しが記録されます。最後のウィンドウが閉じたあとも、バックエンドの呼び出しは続けられますが、ウィンドウが再接続されるまで、動作状況のパネルも承認カードも表示されません。

ブラウザの claude.ai から接続できない理由

「ブラウザの claude.ai から接続できない理由」セクション

クラウドのチャットサービスは、お使いのマシンの 127.0.0.1 に到達できません。代わりに Claude Desktop や、Claude Code、Cursor などを使ってください。MCP のポートを公開インターネットにトンネルしてはいけません。URL を知っている人なら誰でも、ローカルのプロジェクトのファイルを編集、削除できてしまいます。

症状試すこと
一部のツールが使えない図のプレビューなど、UI を必要とするツールには Oleafly のウィンドウが必要です。アプリとプロジェクトを開いてから、tools/list をやり直してください。
ポートが 5323 から変わった優先するポートが使えなかったため、Oleafly が空いているポートを選びました。設定から実際の URL をコピーしてください。
HTTP 401トークンが一致していません(再発行したあとなど)。新しいトークンをクライアントにコピーしてください。
HTTP 403クライアントが Origin ヘッダーまたはループバック以外の Host を送信しました。ブラウザのタブではなく、ネイティブの MCP クライアントを使ってください。
呼び出しがタイムアウトした各ツールの呼び出しは、コンパイルや、あなたが承認をクリックするのを、最大で 5 分 (300 秒) 待ちます。保留中のカードを承認または却下するか、やり直してください。コンパイルはそれより長くかかることがあり、Quarto や Calepin のノートブックでは最大 1 時間です。呼び出しがタイムアウトしたあとも Oleafly の中で実行が続き、Oleafly のウィンドウを必要とするツールはそれを待つので、やり直す前に終わらせてください。
compile がエラーの代わりに理由を返すビルドを実行できませんでした。たとえば TeX がインストールされていません。TinyTeX のインストールなど、アプリで Oleafly が示す対処法を使ってから、もう一度コンパイルしてください。
接続できないOleafly が、MCP を有効にした状態で起動している必要があります。このサーバーは終了すると止まります。アプリを閉じたままプロジェクトのツールを使うには、代わりにクライアントを oleafly mcp に接続してください。
設定 → AI アシスタント → MCP。サーバーの追加、レジストリの閲覧、ほかのツールの設定の読み込みができます。
設定 → AI アシスタント → MCP。サーバーの追加、レジストリの閲覧、ほかのツールの設定の読み込みができます。 スクリーンショット全体を開く

組み込みのアシスタントにツールを増やすには 設定 → AI アシスタント → MCP を開きます。

  • レジストリを見る で、サーバーを探して、その設定を確認します。
  • ほかのツールから読み込む で、既存のサーバー設定を選びます。読み込む前に、選んだ項目を確認してください。
  • サーバーを追加 で、サーバーを自分で入力し、接続を検証します。

接続したサーバーは、そのツールをアシスタントに提供します。接続の状態の確認と、サーバーの有効化・無効化は、同じページから行えます。認証情報とコマンドは各サーバーの設定に属するので、新しいサーバーを接続する前に確認してください。

alphaXiv も MCP サーバーとして接続されますが、設定はここではなく 設定 → 連携 → alphaXiv で API キーを使って行います。接続すると、この一覧に alphaXiv として表示されます。手順は研究用の情報源を接続するで説明しています。

外部サーバーを手動で設定する

「外部サーバーを手動で設定する」セクション
サーバーを追加 → フォーム。ローカルのコマンドかリモートの URL を選び、接続用の項目を入力して、追加と検証を行います。
サーバーを追加 → フォーム。ローカルのコマンドかリモートの URL を選び、接続用の項目を入力して、追加と検証を行います。 スクリーンショット全体を開く

設定 → AI アシスタント → MCP で サーバーを追加 を選びます。ローカルのサーバーは stdio でコマンドを実行し、リモートのサーバーは URL に接続します。JSON フォームでは、Oleafly のサーバー形式を使います。

ローカルサーバーの設定
{
"name": "Research tools",
"enabled": true,
"transport": "stdio",
"command": "your-mcp-server",
"args": ["--stdio"],
"env": {}
}

コマンドと引数は、インストールしたサーバーのドキュメントにあるものに置き換えます。環境変数の値は env オブジェクトに入れます。

リモートサーバーの設定
{
"name": "Research service",
"enabled": true,
"transport": "remote",
"url": "https://your-server.example/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}

例の URL とトークンは、サービスの接続情報に置き換えます。 検証 で接続を確認し、サーバーが提供するツールを確認します。サーバーの有効化と無効化は、その行から行います。編集の操作で設定を変更し、削除の操作で接続を解除します。

ほかのツールから読み込む を選び、見つかった設定を確認して、必要なサーバーを選びます。読み込む前に、実行ファイルのパス、環境変数、URL、認証情報を確認してください。読み込まれるのは接続設定で、サーバーの実行ファイルがインストールされるわけではありません。

  1. Oleafly で、練習用の小さなプロジェクトを開きます。
  2. アプリからコピーしたスニペットを使って、外部のクライアントを接続します。
  3. クライアントに、get_status を呼び出してプロジェクトのファイルを一覧にするよう頼みます。
  4. メイン文書を読んで、タイトルの変更案を出すよう頼みます。
  5. 書き込みを承認する前に、Oleafly でその操作を確認します。
  6. コンパイルして、PDF を確認します。

Oleafly の中で外部ツールを接続した場合は、そのサーバーが対応している、読み取りだけの簡単な依頼から始めて、チャットに表示されるツールカードを確認します。

画像のプレビュー

AI の回答を読み込めませんでした

もう一度試すか、ドキュメントを検索してください。