連接
透過 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 金鑰貼進 設定,就適合用這個方式。
啟用它
標題為「啟用它」的段落- 開啟 設定 → 整合 → Oleafly MCP。
- 開啟 啟用 MCP 伺服器。
伺服器只會在 Oleafly 程序開啟期間執行。它只在 127.0.0.1 上接聽,絕不會在你的區域網路上接聽。關閉專案視窗不會停止伺服器。關閉 MCP 或結束 Oleafly 才會。
Oleafly 偏好使用連接埠 5323(http://127.0.0.1:5323/mcp)。如果它無法使用,伺服器會自動綁定另一個空閒的本機連接埠,並儲存起來供下次啟動使用。設定中會顯示目前使用中的 URL。它的重新啟動按鈕會盡可能沿用目前的連接埠,否則選擇另一個空閒的連接埠。
連接你的用戶端
標題為「連接你的用戶端」的段落設定中提供常見用戶端可複製貼上的片段。請複製即時的 URL,因為所選的連接埠可能與 5323 不同,然後把 <token> 換成設定中的 bearer 權杖(顯示/複製)。
Claude Code
標題為「Claude Code」的段落claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"Claude Desktop
標題為「Claude Desktop」的段落加入 claude_desktop_config.json(透過 mcp-remote 的 stdio 橋接,因為 Desktop 偏好 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 擴充功能
標題為「Claude Desktop 擴充功能」的段落每個版本都附帶 oleafly.mcpb,這是一個 Claude Desktop 擴充功能,因此不需要設定檔或權杖。從最新版本 (在新分頁開啟)下載,用 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 / VS Code」的段落寫入 .cursor/mcp.json(或你的用戶端的 MCP 設定檔):
{ "mcpServers": { "oleafly": { "url": "http://127.0.0.1:5323/mcp", "headers": { "Authorization": "Bearer <token>" } } }}Grok CLI
標題為「Grok CLI」的段落寫入 ~/.grok/config.toml:
[mcp_servers.oleafly]url = "http://127.0.0.1:5323/mcp"headers = { Authorization = "Bearer <token>" }Codex CLI
標題為「Codex CLI」的段落請使用 Oleafly 設定中的 Codex CLI 片段,它提供連到執行中伺服器的 stdio 橋接。把這個項目加入你的 Codex 設定,並使用 Oleafly 顯示的即時 URL 和權杖:
[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 助理 → 技能 中的 與這台電腦上的其他代理程式共用技能。請參閱 技能。
當 設定 → 實驗功能 中的 筆記 開啟時,就會有這些工具,開啟方式請見開啟筆記。它們處理的是你的筆記,而不是開啟中的專案,而且需要已連接的視窗。
| 工具 | 功能 |
|---|---|
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 無法連接
標題為「為什麼瀏覽器中的 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 新增外部工具
標題為「為 Oleafly 新增外部工具」的段落
要讓內建的助理擁有更多工具,請開啟 設定 → AI 助理 → MCP。
- 瀏覽註冊庫,尋找伺服器並檢視它的設定方式。
- 從其他工具匯入,選取現有的伺服器設定。匯入之前請檢視所選的項目。
- 新增伺服器,自己輸入伺服器,然後驗證連線。
已連線的伺服器會把它們的工具提供給助理。你可以在同一頁檢視連線狀態,並啟用或停用伺服器。憑證和指令屬於各伺服器自己的設定;連接新的伺服器之前請先檢視。
alphaXiv 也是以 MCP 伺服器的形式連接,但你是在 設定 → 整合 → alphaXiv 用 API 金鑰設定,而不是在這裡。連接之後,它會以 alphaXiv 之名出現在這份清單中。步驟請見 連接研究來源。
手動設定外部伺服器
標題為「手動設定外部伺服器」的段落
在 設定 → 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 和權杖換成該服務的連線資訊。使用 驗證 來檢查連線,然後檢視伺服器提供的工具。從伺服器所在的列啟用或停用它。使用它的編輯動作變更設定,使用它的移除動作中斷連接。
匯入現有的 MCP 設定
標題為「匯入現有的 MCP 設定」的段落選擇 從其他工具匯入,檢視找到的設定,並選取你想要的伺服器。匯入之前,請檢視執行檔路徑、環境變數、URL 和憑證。這只會匯入連線設定;不會替你安裝伺服器的執行檔。
試試連線
標題為「試試連線」的段落- 在 Oleafly 中開啟一個小型的練習專案。
- 用從應用程式複製的片段連接外部用戶端。
- 請用戶端呼叫
get_status並列出專案檔案。 - 請它讀取主要文件並建議修改標題。
- 核准寫入之前,先在 Oleafly 中檢視這個動作。
- 編譯並檢查 PDF。
要在 Oleafly 內使用已連接的外部工具,請先從該伺服器支援的簡單唯讀請求開始,並檢視聊天中產生的工具卡片。