office-mcp 是直接讀寫 Office 檔案的本機 MCP 伺服器。你可以讓 AI 建立會議紀錄、修改段落、加入表格,再交出可開啟的 DOCX;不需要讓它操作 Word 視窗。這篇選用 gawirable 的實作,適合規則清楚的文件整理。需要追蹤修訂、逐頁排版或在開啟中的文件即時協作時,這條檔案路線就不夠。
安裝並接上 AI
需要 Git、uv 與 Python 3.12。在新資料夾的 PowerShell 執行:
git clone --depth 1 https://github.com/gawirable/office-mcp.git office-mcp
uv venv --python 3.12 .venv
uv pip install --python .\.venv\Scripts\python.exe .\office-mcp
New-Item -ItemType Directory -Force documents | Out-Null
$server = (Resolve-Path .\.venv\Scripts\office-mcp.exe).Path
$docs = (Resolve-Path .\documents).Path
這份原始碼的版本是 0.1.0。虛擬環境要自行建立,不要假設下載下來就附有可用的 .venv。
Claude Code:
claude.cmd mcp add office --scope project --env PYTHONUTF8=1 --env PYTHONIOENCODING=utf-8 --env "OFFICE_MCP_DEFAULT_FOLDER=$docs" -- $server
claude.cmd mcp list
確認 Connected 後重新開啟專案工作階段。Codex:
codex mcp add office --env PYTHONUTF8=1 --env PYTHONIOENCODING=utf-8 --env "OFFICE_MCP_DEFAULT_FOLDER=$docs" -- $server
codex mcp list
Codex 設定保存在使用者層;預設文件資料夾讓 meeting-notes.docx 這種相對檔名有固定位置,不是檔案存取隔離。Cursor 可依上游設定結構,在 .cursor/mcp.json 的 mcpServers 指定相同執行檔及三個環境變數;客戶端檔案格式請參考 Cursor MCP 文件。
三個實用任務
1. 把會議內容整理成 Word
只用 office MCP,在預設文件資料夾建立 meeting-notes.docx,標題「會議紀錄」。
加入一級標題「待辦事項」、段落「週一提交報告」,再加入兩欄表格:
負責人,期限;小陳,週一。完成後列出段落並回報表格數。
我們得到三個段落及一個表格。工具的段落索引從 0 開始;word_list_paragraphs 可以讀到標題樣式,適合在下一次修改前先定位目標。
2. 修改期限,確認修改範圍
用 word_find_replace 將 meeting-notes.docx 的「週一」改成「週二」。
回報實際替換次數,再列出所有段落;不要假設表格也已經修改。
實際只替換 1 次,段落變成「週二提交報告」。我們另外檢查存檔,表格仍是「小陳/週一」。這個版本的 word_find_replace 處理正文段落,不是整份文件所有位置的搜尋取代;它也沒有表格讀取工具可直接回查儲存格。遇到跨段落與表格的期限更新,應分別驗證,不能把一次成功回應當成全部完成。
3. 匯出 HTML 給同事確認內容
用 word_export_html 將 meeting-notes.docx 匯出為 meeting-notes.html,
回報完整輸出路徑。保留原 DOCX,不要改成 PDF 匯出。
DOCX 轉 HTML 使用 Mammoth,不需要 LibreOffice。我們的輸出保留中文、待辦標題與表格,適合做內容檢查;它不是 Word 分頁版面的複製品。
常見錯誤與處理
- 段落索引超出範圍: 我們傳入 999,收到
Paragraph index 999 is out of range (document has 3 paragraph(s))。先word_list_paragraphs,使用回傳索引,不要把畫面上的「第 1 段」直接當索引 1。 - 找不到
soffice: PDF 等匯出依賴 LibreOffice;基本 DOCX 編輯與 DOCX→HTML 不需要它。先確認你要交付的格式,再安裝額外程式。 - 中文亂碼: 把
PYTHONUTF8=1和PYTHONIOENCODING=utf-8放在客戶端的伺服器環境設定。只在另一個終端機設定,未必會傳給 AI 啟動的程序。 - 文件無法存檔: 如果 Word 鎖住檔案,先關閉該文件再修改,或在副本上操作。上游會把這類存檔問題回報為檔案鎖定;反覆重試不會解除 Word 的鎖。
成本、限制與其他選擇
上游專案的套件中繼資料宣告 MIT 授權。基本操作只需要本機 Python 套件,不需要 Office 帳戶或服務 API key;AI 客戶端用量另計。它不控制開啟中的 Word,也沒有把預設資料夾變成安全沙箱。先用文件副本,避免覆蓋唯一原件。
大量 Markdown 內容要一次轉成 Word,可以用 Pandoc 的轉檔路線;只想從既有文件擷取內容,參考 MarkItDown。如果主要工作是試算表公式,則選專門的 Excel 工具,比把 DOCX 工具當試算表助手清楚。
FAQ
Word MCP 和 Office-Word-MCP-Server 是同一個專案嗎?
不是。本文使用 gawirable/office-mcp,套件入口是 office-mcp.exe。搜尋結果中的 GongRzhe/Office-Word-MCP-Server 是另一個專案,已歸檔;不要將它的套件名稱或工具參數貼進這份設定。
不裝 Word 可以建立 DOCX 嗎?
可以,這個伺服器透過 Python 文件套件讀寫 DOCX。安裝 Word 不是本例的前提,但文件在 Word 裡的實際分頁仍需交付前檢查。DOCX 建立成功不等於完成版面校對。
為什麼替換文字後,表格裡的期限沒變?
0.1.0 的 word_find_replace 走正文段落,不會替你更新表格儲存格。我們在同一份文件放入兩個「週一」,工具回報一次替換,存檔也只改了段落。需要更新表格時,先確認客戶端是否有適合的其他工具,或使用可檢查儲存格的文件程式處理。
我們測了什麼
2026-11-16:Windows、Python 3.12、office-mcp 原始碼 0.1.0、MCP SDK 1.30.0。Codex 建立中文 DOCX、加入表格、替換段落、匯出 HTML 並取得索引錯誤;以文件套件檢查存檔,確認表格未被替換。Claude Code 完成註冊與 Connected 檢查。Cursor、PDF 匯出、Word 視窗與逐頁版面未測。參考官方 README與實際 Word 工具,查閱日期同上。