Third-party toolUpdated 2026.11.18

Word MCP on Windows: Edit DOCX Files with Claude Code and Codex

Create and edit DOCX files on Windows with office-mcp, Claude Code and Codex. Test Chinese text, paragraph replacement scope and HTML export without Microsoft Word.

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.

Subscribe to AI tool picks and practical advice

Get worthwhile tool picks, test findings and important updates in your inbox.

Get a monthly-updated list of AI tools and Skills right away. We email when there are worthwhile tool picks, test findings or important updates. Unsubscribe anytime. Privacy

Almost done: check your inboxClick the button in the confirmation email and you will get the download link for the tool list. If you do not see it, check your spam or Promotions folder.

Past issues

Or follow us on: