Skip to content
Back to search

word-mcp-live

The only MCP server that edits Word documents while they're open — 114 tools, live editing, tracked changes, per-action undo

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ykarapazar--word-mcp-live/badge.svg)](/listings/ykarapazar--word-mcp-live)

HTML

<a href="/listings/ykarapazar--word-mcp-live"><img src="/api/listings/ykarapazar--word-mcp-live/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pip install word-mcp-live

Or install from source:

git clone https://github.com/ykarapazar/word-mcp-live.git
cd word-mcp-live
pip install -e .

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 420 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=word&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJ3b3JkLW1jcC1saXZlIl19)
  3. # word-mcp-live
  4. **The only MCP server that edits Word documents while they're open**
  5. `Live editing` &middot; `Tracked changes` &middot; `Per-action undo` &middot; `120 tools` &middot; `Cross-platform`
  6. [![PyPI](https://img.shields.io/pypi/v/word-mcp-live?color=blue)](https://pypi.org/project/word-mcp-live/)
  7. [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
  8. [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
  9. [![Platform: Windows + macOS/Linux](https://img.shields.io/badge/platform-Windows%20%2B%20macOS%2FLinux-lightgrey)]()
  10. </div>
  11. ---
  12. word-mcp-live gives any AI assistant that supports [MCP](https://modelcontextprotocol.io/) full control of Microsoft Word. Open a document, tell the AI what you need, and watch it happen — formatting, tracked changes, comments, and all. Changes appear live in your open document.
  13. <table>
  14. <tr>
  15. <td width="50%">
  16. ### Without word-mcp-live
  17. - AI can discuss your document but can't touch it
  18. - You copy-paste between AI and Word, losing formatting
  19. - Track changes? You do those manually after the fact
  20. - Every edit means save → close → process → reopen
  21. </td>
  22. <td width="50%">
  23. ### With word-mcp-live
  24. - "Add a tracked change replacing ABC Corp with XYZ Ltd" — done
  25. - Changes appear live in your open Word document
  26. - Every AI edit is one Ctrl+Z away
  27. - Real tracked changes with your name, not XML hacks
  28. </td>
  29. </tr>
  30. </table>
  31. ### See it in action
  32. https://github.com/user-attachments/assets/fbb09af4-1e25-4e49-94d0-45b363278810
  33. ## What Sets This Apart
  34. - **Live editing** — Edit documents while they're open in Word. No save-close-reopen cycle.
  35. - **Full undo** — Every AI action is a single Ctrl+Z. Made a mistake? Just undo it.
  36. - **Native tracked changes** — Real Word revisions with your name, not XML hacks.
  37. - **Threaded comments** — Add, reply, resolve, and delete comments like a human reviewer.
  38. - **Layout diagnostics** — Detects formatting problems before they become print disasters.
  39. - **Equations & cross-references** — Insert math formulas and auto-updating references.
  40. - **120 tools** — The most comprehensive Word MCP server available.
  41. ## Quick Start
  42. ```bash
  43. pip install word-mcp-live
  44. ```
  45. Or install from source:
  46. ```bash
  47. git clone https://github.com/ykarapazar/word-mcp-live.git
  48. cd word-mcp-live
  49. pip install -e .
  50. ```
  51. ## Client Installation
  52. <details open>
  53. <summary><b>Claude Desktop</b></summary>
  54. Add to your `claude_desktop_config.json`:
  55. ```json
  56. {
  57. "mcpServers": {
  58. "word": {
  59. "command": "uvx",
  60. "args": ["word-mcp-live"],
  61. "env": {
  62. "MCP_AUTHOR": "Your Name",
  63. "MCP_AUTHOR_INITIALS": "YN"
  64. }
  65. }
  66. }
  67. }
  68. ```
  69. </details>
  70. <details>
  71. <summary><b>Claude Code</b></summary>
  72. Add to your `.mcp.json`:
  73. ```json
  74. {
  75. "mcpServers": {
  76. "word": {
  77. "command": "uvx",
  78. "args": ["word-mcp-live"],
  79. "env": {
  80. "MCP_AUTHOR": "Your Name",
  81. "MCP_AUTHOR_INITIALS": "YN"
  82. }
  83. }
  84. }
  85. }
  86. ```
  87. </details>
  88. <details>
  89. <summary><b>Cursor</b></summary>
  90. **One-click:** Click the install button at the top of this page.
  91. **Manual:** Add to `~/.cursor/mcp.json`:
  92. ```json
  93. {
  94. "mcpServers": {
  95. "word": {
  96. "command": "uvx",
  97. "args": ["word-mcp-live"],
  98. "env": {
  99. "MCP_AUTHOR": "Your Name",
  100. "MCP_AUTHOR_INITIALS": "YN"
  101. }
  102. }
  103. }
  104. }
  105. ```
  106. </details>
  107. <details>
  108. <summary><b>VS Code / Copilot</b></summary>
  109. **One-click:** [Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%20%22word%22%2C%20%22command%22%3A%20%22uvx%22%2C%20%22args%22%3A%20%5B%22word-mcp-live%22%5D%7D)
  110. **Manual:** Add to your VS Code `settings.json`:
  111. ```json
  112. {
  113. "mcp": {
  114. "servers": {
  115. "word": {
  116. "command": "uvx",
  117. "args": ["word-mcp-live"],
  118. "env": {
  119. "MCP_AUTHOR": "Your Name",
  120. "MCP_AUTHOR_INITIALS": "YN"
  121. }
  122. }
  123. }
  124. }
  125. }
  126. ```
  127. </details>
  128. <details>
  129. <summary><b>Windsurf</b></summary>
  130. Add to `~/.codeium/windsurf/mcp_config.json`:
  131. ```json
  132. {
  133. "mcpServers": {
  134. "word": {
  135. "command": "uvx",
  136. "args": ["word-mcp-live"],
  137. "env": {
  138. "MCP_AUTHOR": "Your Name",
  139. "MCP_AUTHOR_INITIALS": "YN"
  140. }
  141. }
  142. }
  143. }
  144. ```
  145. </details>
  146. <details>
  147. <summary><b>OpenAI Codex (CLI, desktop app, IDE)</b></summary>
  148. ```bash
  149. codex mcp add word --env MCP_AUTHOR="Your Name" -- uvx word-mcp-live
  150. ```
  151. Or add to `~/.codex/config.toml`:
  152. ```toml
  153. [mcp_servers.word]
  154. command = "uvx"
  155. args = ["word-mcp-live"]
  156. startup_timeout_sec = 60
  157. tool_timeout_sec = 120
  158. [mcp_servers.word.env]
  159. MCP_AUTHOR = "Your Name"
  160. ```
  161. In the desktop app: Settings → MCP servers → Add server. On Windows, run Codex natively, not under WSL — live tools need native Windows.
  162. </details>
  163. <details>
  164. <summary><b>Docker</b></summary>
  165. ```json
  166. {
  167. "mcpServers": {
  168. "word": {
  169. "command": "docker",
  170. "args": ["run", "-i", "--rm", "ghcr.io/ykarapazar/word-mcp-live"],
  171. "env": {
  172. "MCP_AUTHOR": "Your Name",
  173. "MCP_AUTHOR_INITIALS": "YN"
  174. }
  175. }
  176. }
  177. }
  178. ```
  179. > Note: Docker mode supports cross-platform tools only. Live editing requires a native (non-Docker) install on Windows or macOS with Word running.
  180. </details>
  181. > **`MCP_AUTHOR`** sets your name on tracked changes and comments (default: `"Author"`). **`MCP_AUTHOR_INITIALS`** sets comment initials.
  182. ## Two Modes
  183. | | Works everywhere | Live editing (Word open) |
  184. |---|---|---|
  185. | **What it does** | Create and edit saved .docx files | Edit documents live while you work in Word |
  186. | **Platform** | Windows, macOS, Linux | Windows (COM) and macOS (JXA) |
  187. | **Undo** | File-level saves | Per-action Ctrl+Z (Windows); per-operation undo (macOS) |
  188. | **Best for** | Batch processing, document generation | Interactive editing, formatting, review |
  189. Both modes work together. The AI picks the right one for the task.
  190. ### macOS Live Editing (New in v1.5.0)
  191. Live tools now work on macOS via JavaScript for Automation (JXA). Same tool names, same parameters — the server detects your platform and uses the right automation backend.
  192. | Feature | Windows | macOS |
  193. |---------|---------|-------|
  194. | Text read/write/find/replace | COM | JXA |
  195. | Formatting (bold, font, style) | COM | JXA |
  196. | Track changes & revisions | COM | JXA |
  197. | Comments (add, delete, list) | COM | JXA |
  198. | Tables (add, read, modify rows/cells) | COM | JXA |
  199. | Page layout, headers, bookmarks | COM | JXA |
  200. | Table formatting (`word_live_format_table`) | COM | Not available |
  201. | Images, multi-paragraph insert | COM | Not available |
  202. | Equations, cross-references | COM | Not available |
  203. | Snapshot diff/status, document properties | COM | Not available |
  204. | Threaded comment replies | COM | Not available |
  205. | Comment resolve/unresolve | COM | Not available |
  206. | Undo history inspection | COM | Not available |
  207. | Watermarks | COM | Not available |
  208. ## Configuration
  209. | Variable | Default | Description |
  210. |----------|---------|-------------|
  211. | `MCP_AUTHOR` | `"Author"` | Author name for tracked changes and comments |
  212. | `MCP_AUTHOR_INITIALS` | `""` | Author initials for comments |
  213. | `MCP_TRANSPORT` | `stdio` | Transport type: `stdio`, `sse`, or `streamable-http` |
  214. | `MCP_HOST` | `0.0.0.0` | Host to bind (for SSE/HTTP transports) |
  215. | `MCP_PORT` | `8000` | Port to bind (for SSE/HTTP transports) |
  216. For remote deployment, see [RENDER_DEPLOYMENT.md](RENDER_DEPLOYMENT.md).
  217. ## Example Prompts
  218. Just tell the AI what you want in plain language:
  219. ```
  220. "Draft a contract with tracked changes so my colleague can review"
  221. "Format all headings as Cambria 13pt bold and add automatic numbering"
  222. "Add a comment on paragraph 3 asking about the deadline"
  223. "Find every mention of 'ABC Corp' and replace with 'XYZ Ltd' as a tracked change"
  224. "Set the page to A4 landscape with 2cm margins"
  225. "Insert a table of contents based on the document headings"
  226. "Add page numbers in the footer and our company name in the header"
  227. "Insert a cross-reference to Heading 2 in paragraph 5"
  228. ```
  229. ## Usage Examples
  230. ### Example 1: Read a document (cross-platform)
  231. **Tool call:** `get_document_text`
  232. ```json
  233. { "filename": "C:/Documents/report.docx" }
  234. ```
  235. **Expected output:**
  236. ```json
  237. {
  238. "status": "success",
  239. "paragraphs": [
  240. {"index": 0, "text": "Quarterly Report", "style": "Heading 1"},
  241. {"index": 1, "text": "Revenue increased by 15% compared to Q3.", "style": "Normal"},
  242. {"index": 2, "text": "Key Metrics", "style": "Heading 2"}
  243. ],
  244. "total_paragraphs": 3
  245. }
  246. ```
  247. ### Example 2: Live editing with tracked changes (Windows)
  248. **Tool call:** `word_live_replace_text`
  249. ```json
  250. {
  251. "filename": "report.docx",
  252. "find_text": "ABC Corporation",
  253. "replace_text": "XYZ Ltd",
  254. "match_case": true,
  255. "replace_all": true,
  256. "track_changes": true
  257. }
  258. ```
  259. **Expected output:**
  260. ```json
  261. {
  262. "status": "success",
  263. "replacements": 4,
  264. "message": "Replaced 4 occurrences (tracked changes enabled)"
  265. }
  266. ```
  267. The replacements appear as tracked changes in Word with strikethrough on "ABC Corporation" and underline on "XYZ Ltd".
  268. ### Example 3: Add a comment anchored to text (cross-platform)
  269. **Tool call:** `add_comment`
  270. ```json
  271. {
  272. "filename": "C:/Documents/contract.docx",
  273. "target_text": "payment within 30 days",
  274. "comment_text": "Should we extend this to 45 days?",
  275. "author": "Jane Smith"
  276. }
  277. ```
  278. **Expected output:**
  279. ```json
  280. {
  281. "status": "success",
  282. "message": "Comment added by Jane Smith on 'payment within 30 days'"
  283. }
  284. ```
  285. The comment appears in Word's Review panel, anchored to the specified text.
  286. ## Tool Reference
  287. **120 tools** across two modes — see the [complete tool reference](TOOLS.md) for details.
  288. | Category | Count |
  289. |----------|-------|
  290. | Cross-platform (python-docx) | 75 |
  291. | Windows Live (COM automation) | 45 (44 `word_live_*` + `word_screen_capture`) |
  292. | macOS Live (JXA automation) | 32 (of the 45 live tools) |
  293. ## Requirements
  294. - **Python 3.11+**
  295. - `python-docx`, `fastmcp`, `msoffcrypto-tool` (installed automatically)
  296. - **Windows Live tools:** Windows 10/11 + Microsoft Word + `pywin32` (installed automatically)
  297. - **macOS Live tools:** macOS + Microsoft Word for Mac (uses built-in JXA — no extra dependencies)
  298. > The cross-platform tools work without Word installed — only python-docx is needed.
  299. ## Contributing
  300. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style, and how to add new tools.
  301. Found a bug? [Open an issue](https://github.com/ykarapazar/word-mcp-live/issues/new?template=bug_report.md).
  302. Have an idea? [Request a feature](https://github.com/ykarapazar/word-mcp-live/issues/new?template=feature_request.md).
  303. ## Acknowledgments
  304. Built on top of [GongRzhe/Office-Word-MCP-Server](https://github.com/GongRzhe/Office-Word-MCP-Server) by GongRzhe (MIT License).
  305. Additional libraries: [python-docx](https://python-docx.readthedocs.io/) &middot; [FastMCP](https://github.com/modelcontextprotocol/python-sdk) &middot; [pywin32](https://github.com/mhammond/pywin32)
  306. ## Privacy
  307. This server runs entirely on your local machine. No data is collected, transmitted, or stored. See the full [Privacy Policy](PRIVACY.md).
  308. ## Support
  309. - **Bug reports:** [Open an issue](https://github.com/ykarapazar/word-mcp-live/issues/new?template=bug_report.md)
  310. - **Feature requests:** [Request a feature](https://github.com/ykarapazar/word-mcp-live/issues/new?template=feature_request.md)
  311. - **Discussions:** [GitHub Discussions](https://github.com/ykarapazar/word-mcp-live/discussions)
  312. ## License
  313. MIT License — see [LICENSE](LICENSE) for details.
  314. ## Star History
  315. <a href="https://star-history.com/#ykarapazar/word-mcp-live&Date">
  316. <picture>
  317. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=ykarapazar/word-mcp-live&type=Date&theme=dark" />
  318. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=ykarapazar/word-mcp-live&type=Date" />
  319. <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=ykarapazar/word-mcp-live&type=Date" />
  320. </picture>
  321. </a>
  322. <!-- mcp-name: io.github.ykarapazar/word-mcp-live -->

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.