# 透過 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（或類似服務），並且想讓那個聊天應用程式來驅動 Oleafly，而不必把 API 金鑰貼進 [設定](/docs/ai-setup/)，就適合用這個方式。

## 啟用它

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)。
:::

設定中提供常見用戶端可複製貼上的片段。請複製即時的 URL，因為所選的連接埠可能與 `5323` 不同，然後把 `<token>` 換成設定中的 bearer 權杖（顯示／複製）。

### 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`（透過 `mcp-remote` 的 stdio 橋接，因為 Desktop 偏好 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 擴充功能

每個版本都附帶 `oleafly.mcpb`，這是一個 Claude Desktop 擴充功能，因此不需要設定檔或權杖。從[最新版本](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 中，圖片是 Typst 標記，例如 CeTZ 畫布或 fletcher 圖表，以專案的 Typst 版本轉譯。`insert_figure` 會把它包進 `#figure`，把標籤放在它後面，並把它的 `#import` 行移到它上方。
- 在 Markdown 專案中，兩個工具都會傳回錯誤，而且不會更動任何東西。

`load_image` 在每個專案中都能使用。

### 應用程式

| 工具 | 功能 |
|---|---|
| `toggle_theme` | 切換淺色／深色模式 |

### 技能

| 工具 | 功能 |
|---|---|
| `list_skills` | 列出已安裝的技能，含它們的 ID、名稱、描述，以及是否已開啟 |
| `load_skill` | 載入某個技能的完整指示和它的檔案清單 |
| `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 讀取一則筆記，包含它的 front matter |
| `today_note` | 讀取今天的每日筆記；如果它還不存在，則回傳它將會使用的標題 |
| `list_note_tasks` | 列出你的筆記中的核取方塊任務，最新的筆記在前。可依筆記，以及未完成或已完成篩選 |
| `note_backlinks` | 列出連結到某則筆記的筆記，並附上每個連結周圍的文字 |
| `append_to_note` | 把 Markdown 加到某則筆記或今天的每日筆記的結尾 |
| `edit_note_section` | 改寫筆記中某個標題底下的部分，或加到它的結尾 |
| `create_note` | 建立一則筆記，包含標題、Markdown、標籤和連結的專案 |

`append_to_note` 和 `edit_note_section` 不會直接寫入筆記。在你於 Oleafly 中接受之前，它們的變更會在筆記中以建議的形式顯示。`create_note` 會等待你在 Oleafly 中核准，`append_to_note` 在必須先建立今天的每日筆記時也一樣。在 **信任這個連線** 下，建立筆記不會詢問。透過協作伺服器共用的筆記可以讀取，但無法用這種方式變更。**唯讀** 會移除這三個變更筆記的工具。

## 核准與安全

許多 MCP 用戶端在呼叫工具之前會先詢問。Oleafly 也會套用你在 **設定 → 整合 → Oleafly MCP** 中選擇的政策：

- **每項變更都要確認** 是預設值。有應用程式視窗連線時，寫入、重新命名和刪除都會顯示核准卡片。沒有視窗時，這些操作會被拒絕，因為沒有地方可以顯示卡片。
- **自動核准編輯，刪除需確認** 讓寫入和重新命名在後端執行。刪除仍需要有連線的視窗來確認。
- **信任這個連線** 讓後端的寫入和重新命名不經 Oleafly 提示就能執行。刪除仍然需要有連線的視窗。只有在你信任用戶端和它自己的核准控制時，才使用這個政策。

另有兩個開關提供支援：

- **唯讀**（獨立的開關）會把會變更內容的工具完全從 `tools/list` 中移除，所以不論上述政策為何，外部應用程式都只能讀取和編譯，絕不能修改檔案。
- **Bearer 權杖**：256 位元的隨機值，存放在 `~/.oleafly/` 下經過驗證的加密本機儲存空間。重新產生它，就能讓舊的用戶端失效。一般的設定讀取絕不會洩漏權杖。只有執行中伺服器的連線控制項，才能在設定中顯示它。

以及兩項你不需要設定的不變條件：

- **僅限 localhost**：綁定位址是 `127.0.0.1`。帶有瀏覽器 `Origin` 標頭的請求會被拒絕，而且 `Host` 必須是 loopback。
- **專案限制**：後端的檔案工具接受相對於專案的路徑，並把規範化的路徑限制在應用程式所回報的專案內。工具呼叫不能提供另一個專案 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` 標頭或非 loopback 的 `Host`。請使用原生的 MCP 用戶端，不要用瀏覽器分頁。 |
| 呼叫逾時 | 每次工具呼叫最多會等 **5 分鐘**（300 秒），讓編譯完成或等你按下核准。請核准或拒絕待處理的卡片，或重試。編譯可能花更久，Quarto 或 Calepin 筆記本最久可達一小時。呼叫逾時之後，它仍會在 Oleafly 中繼續執行，而需要 Oleafly 視窗的工具會等它完成，所以請讓它先跑完再重試。 |
| `compile` 傳回原因而不是錯誤 | 建置無法執行，例如因為沒有安裝 TeX。請使用 Oleafly 在應用程式中提供的修正方式，例如安裝 TinyTeX，然後再編譯一次。 |
| 無法連線 | 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 內使用已連接的外部工具，請先從該伺服器支援的簡單唯讀請求開始，並檢視聊天中產生的工具卡片。
