The gawirable office-mcp server lets an assistant create and edit local Office files without driving a Word window. It suits structured meeting notes, paragraph changes and simple tables when you need an actual DOCX deliverable. Choose another workflow for tracked changes, live collaboration inside Word or precise page layout. Several projects use similar Word MCP names; this guide uses gawirable/office-mcp.
Install and connect
In a new PowerShell working directory, with Git, uv and Python 3.12 available:
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
The source identifies itself as version 0.1.0. Create your own environment rather than assuming a usable .venv comes with the repository.
For 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
Look for Connected and start a fresh project session. For Codex:
codex mcp add office --env PYTHONUTF8=1 --env PYTHONIOENCODING=utf-8 --env "OFFICE_MCP_DEFAULT_FOLDER=$docs" -- $server
codex mcp list
Codex saves the registration in its user configuration. OFFICE_MCP_DEFAULT_FOLDER supplies a base for relative filenames; it is not an access sandbox. For Cursor, use the same executable and environment under mcpServers in .cursor/mcp.json, following the upstream configuration shape and Cursor MCP documentation.
Three document tasks
Create notes with a heading and table
Use only office MCP. Create meeting-notes.docx in the default folder,
with title 會議紀錄, a level-one heading 待辦事項 and paragraph 週一提交報告.
Add a two-column table: 負責人,期限; 小陳,週一.
List the paragraphs and report the table count afterward.
Our file contained three paragraphs and one table. Paragraph indexes start at zero. word_list_paragraphs also returns styles, so it can identify a heading before an edit.
Replace a deadline and check the scope
Use word_find_replace to change 週一 to 週二 in meeting-notes.docx.
Report the replacement count and list the paragraphs again.
Do not assume the table changed too.
The tool reported one replacement. The paragraph changed, while an independent check of the saved file found 週一 still in the table. In this version, word_find_replace processes body paragraphs; it is not a document-wide replacement covering table cells. There is also no dedicated table-read tool in this interface. Verify separate document regions separately when a change must be exhaustive.
Export an HTML copy for content review
Use word_export_html to export meeting-notes.docx as meeting-notes.html.
Return the full output path. Keep the DOCX and do not switch to PDF export.
DOCX-to-HTML uses Mammoth and does not need LibreOffice. Our output retained the Chinese text, heading and table. HTML is useful for checking content, but does not reproduce Word pagination.
Common errors
- Paragraph index out of range: asking for index 999 returned
Paragraph index 999 is out of range (document has 3 paragraph(s)). List paragraphs first and use the returned zero-based index. - Missing
soffice: PDF and some other exports require LibreOffice. Basic DOCX editing and DOCX-to-HTML do not. Install extra software only for the output route you need. - Broken Chinese text: set both UTF-8 variables in the MCP client's server environment. Variables set in an unrelated terminal may never reach the process the assistant launches.
- A file cannot be saved: Word may hold a lock. Close that document or work on a copy; repeated save calls will not release another application's lock. The upstream maps this case to a file-locked error.
Cost and limits
The project metadata declares MIT licensing. The demonstrated operations need local Python packages rather than an Office account or service API key; AI-client usage is separate. The default folder is a convenience, not a security boundary, and this server does not control an open Word document. Begin with copies of important files.
For converting a complete Markdown document to DOCX, Pandoc is a better-shaped workflow. For extracting an existing document's content, see MarkItDown. Use a dedicated spreadsheet server when formulas and cell-level validation are the main job.
FAQ
Is this the same as Office-Word-MCP-Server?
No. This guide uses gawirable/office-mcp and its office-mcp.exe entry point. GongRzhe's similarly named Office-Word-MCP-Server is a separate, archived project. Its package names and tool parameters should not be mixed into this setup.
Can it create DOCX without Microsoft Word?
Yes. It edits files through Python document libraries rather than Word automation. Inspect final pagination in your target application before delivery, because successful file creation does not validate page layout.
Why did a find-and-replace leave the table unchanged?
Version 0.1.0's replacement tool walks body paragraphs. Our example deliberately placed the same deadline in a paragraph and a table; the response counted one change and the saved file confirmed that scope. Use a workflow that can inspect and edit cells when a deadline update must include tables.
What we tested
2026-11-16: Windows, Python 3.12, office-mcp source version 0.1.0 and MCP SDK 1.30.0. Codex created Chinese notes and a table, replaced paragraph text, exported HTML and received an invalid-index error. Independent file inspection confirmed the unchanged table. Claude Code registration reported Connected. Cursor, PDF export, Word UI and page layout were not tested. References: upstream README and Word tools, accessed the same day.