讓代理來處理您的待辦清單

在找一個能直接操作真實檔案、而不是託管資料庫的待辦事項 MCP 伺服器嗎？taskforge 把它做成一個子指令，taskforge mcp --stdio，專為您的 Obsidian 保管庫服務。把 Claude Desktop 或其他 MCP 客戶端指向它，代理就能透過一小組工具新增、搜尋、編輯及完成任務。它在您的機器上執行，編輯的正是 App 所使用的同一批 Markdown 檔案。沒有託管伺服器，也不需要 API 金鑰。

即將隨 TaskForge 3.0 推出

TaskForge 命令列工具與 MCP 伺服器將隨 TaskForge 3.0 版本一同推出。本頁內容說明的是它們正式上線後的運作方式。TaskForge 應用程式本身現在就能下載使用。

MCP 還是 CLI？

如果您的代理已經與 TaskForge 建立 MCP 連線，請優先使用 MCP 工具。它們具有型別，會回傳結構化錯誤，方便代理據此自我修正，而且不需要在您的 PATH 中安裝任何東西。如果是沒有 MCP 連線的 shell 環境，例如指令碼、cron、CI，或是在儲存庫簽出目錄中工作的程式代理，請改用 CLI。兩者驅動的是同一個引擎，語意完全一致，選擇您執行環境中已經接好的那一個即可。手動編輯保管庫檔案是最後的手段。

安裝

Claude Desktop，一鍵安裝

比較想要精靈式安裝嗎？下載 taskforge 套件包（.mcpb 檔案）並開啟它。Claude Desktop 會引導您完成設定，並詢問您的保管庫資料夾。

上線後即可使用

{
  "mcpServers": {
    "taskforge": {
      "command": "npx",
      "args": ["-y", "taskforge-md", "mcp", "--stdio"],
      "env": {
        "TASKFORGE_VAULT": "/path/to/your/vault"
      }
    }
  }
}

自行從原始碼建置了 taskforge，而不是使用 npx？請將設定直接指向該執行檔：

上線後即可使用

"command": "taskforge",
"args": ["mcp", "--stdio"]

僅支援桌面版，因為 MCP 客戶端都在桌面環境中執行。taskforge 以單一原生執行檔形式提供，支援 macOS、Windows 與 Linux，MCP 伺服器是它的子指令之一。

完整工具集

總共有 22 個工具，涵蓋任務的完整生命週期：新增、讀取、更新、完成、封存與刪除，每項都有對應的批次版本；此外還有移動、重新指定上層任務，以及在行內格式與 TaskNotes 檔案之間轉換；寫入前的 lint 檢查；用於檢查保管庫健康狀態的 doctor 呼叫；以及 schema 與清單資源，讓代理在動手前先了解您的格式。下面這六個是最常用的。每次呼叫都會重新從磁碟讀取保管庫，因此代理操作的永遠是最新的檔案。

query_tasks	搜尋與篩選任務，或讀取已儲存的清單。唯讀。	唯讀
get_task	讀取一項任務及其內容雜湊值。唯讀。	唯讀
add_task	在保管庫的預設位置以您的格式建立任務。	寫入
update_task	變更任務的狀態、優先順序、到期日、標題或標籤。	寫入
complete_task	完成一項任務；如果任務會重複，會回傳下一次發生的任務。	寫入，非冪等
delete_task	刪除一項任務。模型必須完整覆述目前的確切標題，以防操作到過時或幻覺產生的 id。	具破壞性

每個工具現在都帶有註解，讓客戶端一眼就能看出哪些呼叫只是讀取、哪些會寫入、哪一個會刪除。其餘工具還包括 bulk_add_tasks、bulk_update_tasks、bulk_complete_tasks、bulk_delete_tasks、get_tasks、archive_task、move_task、bulk_move_tasks、convert_task、bulk_convert_tasks、outdent_task、bulk_reparent_tasks、lint_task、doctor、list_task_lists 與 get_schema。

三項資源

除了工具之外，伺服器還提供唯讀情境資訊，讓代理在動手之前先了解您保管庫的規則：

taskforge://schema	機器可讀的任務語法：狀態符號、日期格式、自訂欄位、寫入目標。
taskforge://agents-guide	以白話文寫成的保管庫任務慣例指南。
taskforge://lists	您已儲存的任務清單，以及如何為每個清單新增任務。

唯一的要求：保管庫合約

伺服器會讀取 TaskForge 寫入您保管庫中的合約檔案 taskforge/schema.json 與 taskforge/agents.md，藉此了解您確切的任務格式。請至少用 TaskForge 3.0 以上版本開啟過保管庫一次，前往 Settings > AI & Agents，並保持'Generate agent files'開啟。如果保管庫從未在近期的版本中開啟過，伺服器會退回使用通用預設值，並向客戶端發出警告。

如果找不到您的保管庫

伺服器一律會啟動，即使還不知道保管庫在哪裡，因此 Claude Desktop 永遠不會顯示令人一頭霧水的'server failed to start'。當某個工具呼叫無法解析出保管庫時，會回傳一則代理能夠轉達的簡單錯誤訊息：請將 TASKFORGE_VAULT 環境變數設為您的保管庫路徑，或重新安裝套件包，並在系統詢問時輸入保管庫目錄。

僅限本機

taskforge mcp --stdio 只會讀寫您所設定保管庫中的 Markdown 檔案，不會動到其他任何東西。不需要帳號，也不涉及雲端。您原本使用的同步方式，無論是 iCloud、Dropbox 或 Obsidian Sync，都會在裝置之間搬移這些變更。

偏好使用終端機？

如果您想用指令碼處理任務，或執行一次性指令，而不是透過代理操作，taskforge CLI 能以同樣的規則處理同一個保管庫。

安裝 taskforge CLI →

常見問題

什麼是 taskforge MCP 伺服器？

它是內建在 taskforge 執行檔中的本機 Model Context Protocol 伺服器。執行 taskforge mcp --stdio，Claude Desktop 之類的 MCP 客戶端就能透過 22 個具型別的工具（單筆或批次），在您的 Obsidian 保管庫中新增、尋找、編輯、移動、完成和刪除任務。這是一份您的代理能動手處理的待辦清單，不只是讀取而已。

它支援哪些 MCP 客戶端？

任何透過 stdio 使用 MCP 協定的客戶端都可以。Claude Desktop 是最常見的一種，Claude Code、Cursor 和（供 GitHub Copilot 使用的）VS Code 都採用相同的設定方式。每一種都能取得同樣的 22 個工具與三項資源。

這是託管或遠端的 MCP 伺服器嗎？

不是。它在您的機器上透過 stdin 和 stdout 執行，只會動到您指定的保管庫資料夾。沒有網址需要託管，沒有 API 金鑰，也沒有 TaskForge 帳號。這正是重點：您的待辦清單留在您的硬碟上。

我需要事先安裝什麼嗎？

不需要事先安裝。把您客戶端的設定指向 npx -y taskforge-md mcp --stdio，npx 會在第一次執行時下載這個套件。Claude Desktop 使用者也可以直接開啟 .mcpb 套件包，走精靈式安裝。

客戶端說伺服器找不到我的保管庫，該怎麼辦？

伺服器一律會啟動，所以客戶端永遠不會顯示令人一頭霧水的'failed to start'。當某個工具呼叫無法解析出保管庫時，會回傳一則簡單的訊息：把 TASKFORGE_VAULT 環境變數設為您的保管庫路徑，或重新安裝套件包，並在系統詢問時輸入保管庫目錄。

它需要保管庫合約檔案嗎？

是的，這樣才能符合您的格式。它會讀取 taskforge/schema.json 與 taskforge/agents.md，這些檔案在您以'Generate agent files'開啟的狀態下用 TaskForge 3.0 以上版本開啟保管庫時產生。沒有這些檔案，它仍然能執行，但會退回使用通用預設值，並提醒客戶端它是用猜的。