# MCP で接続する

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（または同様のもの）のサブスクリプションがあり、[設定](/docs/ai-setup/)に API キーを貼り付けずに、そのチャットアプリから Oleafly を操作したい場合は、この方法を選びます。

## 有効にする

1. **設定 → 連携 → Oleafly MCP** を開きます。
2. **MCP サーバーを有効にする** をオンにします。

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

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

## クライアントを接続する

:::tip[コピーするトークンはありません]
`oleafly` コマンドには、標準入力と標準出力でやり取りする独自の MCP サーバーがあります。実行中のアプリとそのトークンを自分で見つけるので、URL やトークンをコピーする必要はなく、Node.js も要りません。`oleafly mcp config --client claude-desktop` でセットアップが表示されます。クライアント名は `claude-code`、`claude-desktop`、`codex`、`cursor`、`gemini` です。[コマンドラインツール](/docs/cli/#connect-an-agent-over-mcp)を参照してください。
:::

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

### Claude Code

```bash
claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"
```

### Claude Desktop

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

```json
{
  "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 拡張機能

各リリースには Claude Desktop の拡張機能 `oleafly.mcpb` が含まれているので、設定ファイルやトークンは不要です。[最新リリース](https://github.com/Oleafly/Oleafly/releases/latest)からダウンロードし、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 / VS Code

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

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

### Grok CLI

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

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

### Codex CLI

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

```toml title="~/.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_status` | Oleafly のバージョン、開いているプロジェクト、そのドキュメントエンジン、メイン文書、最後のコンパイルの状態、最後のコンパイルが失敗した、または実行できなかった理由 |
| `list_projects` | ID、名前、エンジン、種類、メイン文書、タイムスタンプ、色、プレビューの状態、書き出しの履歴を含むプロジェクトの一覧 |
| `open_project` | ID を指定してプロジェクトを開き、ほかのツールの対象にする |
| `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_skill` | 1 つのスキルの指示の全文とファイル一覧を読み込む |
| `read_skill_file` | スキルのフォルダにある参考資料やスクリプトを読む |

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

### ノート

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

| ツール | できること |
|---|---|
| `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 から接続できない理由

クラウドのチャットサービスは、お使いのマシンの `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` に接続してください。 |

## Oleafly に外部ツールを追加する

![設定 → AI アシスタント → MCP。サーバーの追加、レジストリの閲覧、ほかのツールの設定の読み込みができます。](https://cdn.oleafly.com/images/screenshots/desktop/docs/settings-mcp-dark-window-v2.png#view=519,89,883,568)

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

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

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

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

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

![サーバーを追加 → フォーム。ローカルのコマンドかリモートの URL を選び、接続用の項目を入力して、追加と検証を行います。](https://cdn.oleafly.com/images/screenshots/desktop/docs/mcp-add-server-dark-window-v2.png#view=670,228,578,625)

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

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

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

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

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

## 既存の MCP 設定を読み込む

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

## 接続を試す

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

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