ms-word-mcp 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. ms_word_mcp-0.1.0/.github/workflows/publish.yml +65 -0
  2. ms_word_mcp-0.1.0/.github/workflows/release-tagged.yml +67 -0
  3. ms_word_mcp-0.1.0/.github/workflows/test.yml +55 -0
  4. ms_word_mcp-0.1.0/.gitignore +12 -0
  5. ms_word_mcp-0.1.0/LICENSE +21 -0
  6. ms_word_mcp-0.1.0/PKG-INFO +198 -0
  7. ms_word_mcp-0.1.0/README.md +171 -0
  8. ms_word_mcp-0.1.0/SECURITY.md +12 -0
  9. ms_word_mcp-0.1.0/docs/PROBES.md +336 -0
  10. ms_word_mcp-0.1.0/docs/ROADMAP.md +129 -0
  11. ms_word_mcp-0.1.0/docs/images/equation-numbers-mac.png +0 -0
  12. ms_word_mcp-0.1.0/docs/reference/equations.md +581 -0
  13. ms_word_mcp-0.1.0/docs/reference/math-autocorrect.json +558 -0
  14. ms_word_mcp-0.1.0/docs/reference/word-object-model.md +1824 -0
  15. ms_word_mcp-0.1.0/docs/research/similar-projects.md +44 -0
  16. ms_word_mcp-0.1.0/pyproject.toml +61 -0
  17. ms_word_mcp-0.1.0/scripts/live_check.py +1118 -0
  18. ms_word_mcp-0.1.0/scripts/probes/find_replace_speed.py +50 -0
  19. ms_word_mcp-0.1.0/scripts/probes/hyperlink_removal.py +42 -0
  20. ms_word_mcp-0.1.0/scripts/probes/mac_bulk_reads.py +62 -0
  21. ms_word_mcp-0.1.0/scripts/probes/mac_core.py +82 -0
  22. ms_word_mcp-0.1.0/scripts/probes/mac_equations.py +57 -0
  23. ms_word_mcp-0.1.0/scripts/probes/mac_floating_pictures.py +157 -0
  24. ms_word_mcp-0.1.0/scripts/probes/mac_layout.py +160 -0
  25. ms_word_mcp-0.1.0/scripts/probes/mac_notes_links.py +162 -0
  26. ms_word_mcp-0.1.0/scripts/probes/mac_shapes.py +243 -0
  27. ms_word_mcp-0.1.0/scripts/probes/mac_tables.py +104 -0
  28. ms_word_mcp-0.1.0/scripts/probes/mac_tables_inactive.py +109 -0
  29. ms_word_mcp-0.1.0/scripts/probes/nested_fields.py +119 -0
  30. ms_word_mcp-0.1.0/scripts/probes/numbered_headings.py +56 -0
  31. ms_word_mcp-0.1.0/scripts/probes/outline_speed.py +63 -0
  32. ms_word_mcp-0.1.0/scripts/probes/paragraph_read_speed.py +53 -0
  33. ms_word_mcp-0.1.0/scripts/probes/picture_crop.py +103 -0
  34. ms_word_mcp-0.1.0/scripts/probes/restart_numbering.py +77 -0
  35. ms_word_mcp-0.1.0/scripts/probes/shape_kinds.py +44 -0
  36. ms_word_mcp-0.1.0/scripts/probes/shape_look.py +64 -0
  37. ms_word_mcp-0.1.0/scripts/probes/shapes_windows.py +322 -0
  38. ms_word_mcp-0.1.0/scripts/probes/windows_checks.py +133 -0
  39. ms_word_mcp-0.1.0/scripts/probes/windows_equations.py +137 -0
  40. ms_word_mcp-0.1.0/scripts/probes/windows_layout.py +123 -0
  41. ms_word_mcp-0.1.0/scripts/probes/windows_math_autocorrect.py +34 -0
  42. ms_word_mcp-0.1.0/scripts/probes/windows_style_add.py +66 -0
  43. ms_word_mcp-0.1.0/scripts/probes/windows_style_steps.py +78 -0
  44. ms_word_mcp-0.1.0/scripts/probes/windows_tables.py +102 -0
  45. ms_word_mcp-0.1.0/scripts/probes/windows_undo_inactive.py +56 -0
  46. ms_word_mcp-0.1.0/src/ms_word_mcp/__init__.py +3 -0
  47. ms_word_mcp-0.1.0/src/ms_word_mcp/backend/__init__.py +27 -0
  48. ms_word_mcp-0.1.0/src/ms_word_mcp/backend/com.py +202 -0
  49. ms_word_mcp-0.1.0/src/ms_word_mcp/backend/documents.py +58 -0
  50. ms_word_mcp-0.1.0/src/ms_word_mcp/backend/mac.py +149 -0
  51. ms_word_mcp-0.1.0/src/ms_word_mcp/backend/worker.py +269 -0
  52. ms_word_mcp-0.1.0/src/ms_word_mcp/server.py +653 -0
  53. ms_word_mcp-0.1.0/src/ms_word_mcp/tools/__init__.py +0 -0
  54. ms_word_mcp-0.1.0/src/ms_word_mcp/tools/_common.py +196 -0
  55. ms_word_mcp-0.1.0/src/ms_word_mcp/tools/_outline.py +121 -0
  56. ms_word_mcp-0.1.0/src/ms_word_mcp/tools/_props.py +828 -0
  57. ms_word_mcp-0.1.0/src/ms_word_mcp/tools/_word.py +404 -0
  58. ms_word_mcp-0.1.0/src/ms_word_mcp/tools/documents.py +306 -0
  59. ms_word_mcp-0.1.0/src/ms_word_mcp/tools/edit.py +54 -0
  60. ms_word_mcp-0.1.0/src/ms_word_mcp/tools/equations.py +333 -0
  61. ms_word_mcp-0.1.0/src/ms_word_mcp/tools/fields.py +537 -0
  62. ms_word_mcp-0.1.0/src/ms_word_mcp/tools/formatting.py +539 -0
  63. ms_word_mcp-0.1.0/src/ms_word_mcp/tools/latex.py +344 -0
  64. ms_word_mcp-0.1.0/src/ms_word_mcp/tools/links.py +514 -0
  65. ms_word_mcp-0.1.0/src/ms_word_mcp/tools/lists.py +416 -0
  66. ms_word_mcp-0.1.0/src/ms_word_mcp/tools/mac.py +1196 -0
  67. ms_word_mcp-0.1.0/src/ms_word_mcp/tools/notes.py +257 -0
  68. ms_word_mcp-0.1.0/src/ms_word_mcp/tools/page.py +726 -0
  69. ms_word_mcp-0.1.0/src/ms_word_mcp/tools/references.py +649 -0
  70. ms_word_mcp-0.1.0/src/ms_word_mcp/tools/screen.py +269 -0
  71. ms_word_mcp-0.1.0/src/ms_word_mcp/tools/shapes.py +1464 -0
  72. ms_word_mcp-0.1.0/src/ms_word_mcp/tools/tables.py +1413 -0
  73. ms_word_mcp-0.1.0/src/ms_word_mcp/tools/text.py +566 -0
  74. ms_word_mcp-0.1.0/src/ms_word_mcp/tools/view.py +147 -0
  75. ms_word_mcp-0.1.0/src/ms_word_mcp/utils/__init__.py +0 -0
  76. ms_word_mcp-0.1.0/src/ms_word_mcp/utils/offload.py +31 -0
  77. ms_word_mcp-0.1.0/tests/conftest.py +43 -0
  78. ms_word_mcp-0.1.0/tests/fakeword.py +978 -0
  79. ms_word_mcp-0.1.0/tests/test_com_undo.py +77 -0
  80. ms_word_mcp-0.1.0/tests/test_documents.py +135 -0
  81. ms_word_mcp-0.1.0/tests/test_fields.py +113 -0
  82. ms_word_mcp-0.1.0/tests/test_formatting.py +275 -0
  83. ms_word_mcp-0.1.0/tests/test_latex.py +47 -0
  84. ms_word_mcp-0.1.0/tests/test_links.py +189 -0
  85. ms_word_mcp-0.1.0/tests/test_lists.py +117 -0
  86. ms_word_mcp-0.1.0/tests/test_mac_parity.py +29 -0
  87. ms_word_mcp-0.1.0/tests/test_notes.py +110 -0
  88. ms_word_mcp-0.1.0/tests/test_outline.py +90 -0
  89. ms_word_mcp-0.1.0/tests/test_page_references.py +110 -0
  90. ms_word_mcp-0.1.0/tests/test_screen.py +20 -0
  91. ms_word_mcp-0.1.0/tests/test_server.py +214 -0
  92. ms_word_mcp-0.1.0/tests/test_shapes.py +443 -0
  93. ms_word_mcp-0.1.0/tests/test_tables.py +66 -0
  94. ms_word_mcp-0.1.0/tests/test_text.py +248 -0
  95. ms_word_mcp-0.1.0/tests/test_view.py +27 -0
  96. ms_word_mcp-0.1.0/tests/test_worker.py +133 -0
  97. ms_word_mcp-0.1.0/uv.lock +1507 -0
@@ -0,0 +1,65 @@
1
+ name: Publish to PyPI
2
+
3
+ # Trigger: when a version tag (e.g. v1.2.3) is pushed to main
4
+ on:
5
+ push:
6
+ tags:
7
+ - 'v[0-9]*.[0-9]*.[0-9]*'
8
+
9
+ jobs:
10
+ # ------------------------------------------------------------------ #
11
+ # Job 0: Gate the release on the same tests PRs run
12
+ # ------------------------------------------------------------------ #
13
+ test:
14
+ name: Tests
15
+ uses: ./.github/workflows/test.yml
16
+
17
+ # ------------------------------------------------------------------ #
18
+ # Job 1: Build the wheel and sdist
19
+ # ------------------------------------------------------------------ #
20
+ build:
21
+ name: Build distribution packages
22
+ needs: test
23
+ runs-on: ubuntu-latest
24
+ steps:
25
+ - uses: actions/checkout@v4
26
+
27
+ - name: Install uv
28
+ uses: astral-sh/setup-uv@v5
29
+
30
+ - name: Set up Python
31
+ run: uv python install
32
+
33
+ - name: Build wheel and sdist
34
+ run: uv build
35
+
36
+ - name: Upload build artifacts
37
+ uses: actions/upload-artifact@v4
38
+ with:
39
+ name: dist
40
+ path: dist/
41
+
42
+ # ------------------------------------------------------------------ #
43
+ # Job 2: Publish to PyPI via Trusted Publishing (OIDC — no token needed)
44
+ # ------------------------------------------------------------------ #
45
+ publish:
46
+ name: Publish to PyPI
47
+ needs: build
48
+ runs-on: ubuntu-latest
49
+ environment:
50
+ name: pypi
51
+ url: https://pypi.org/p/ms-word-mcp
52
+
53
+ # Required for OIDC Trusted Publishing
54
+ permissions:
55
+ id-token: write
56
+
57
+ steps:
58
+ - name: Download build artifacts
59
+ uses: actions/download-artifact@v4
60
+ with:
61
+ name: dist
62
+ path: dist/
63
+
64
+ - name: Publish to PyPI
65
+ uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,67 @@
1
+ name: Release is tagged
2
+
3
+ # A release reaches PyPI because a v* tag was pushed, and for no other reason.
4
+ # publish.yml listens for that tag and nothing else, so a version bump that
5
+ # arrives on main without one is a release that looks finished and was never
6
+ # published. That is what happened to v2.0.0: it sat on main for two days
7
+ # while PyPI stayed at 1.10.0, and it surfaced by accident while cutting the
8
+ # next release.
9
+ #
10
+ # This runs where someone is already looking, on the pull request that takes a
11
+ # release into main.
12
+ on:
13
+ pull_request:
14
+ branches: [main]
15
+ push:
16
+ branches: [main]
17
+
18
+ permissions:
19
+ contents: read
20
+
21
+ jobs:
22
+ tagged:
23
+ name: The version on main has a tag
24
+ runs-on: ubuntu-latest
25
+ steps:
26
+ # Every tag, and enough history to ask whether one is an ancestor.
27
+ - uses: actions/checkout@v4
28
+ with:
29
+ fetch-depth: 0
30
+
31
+ - name: The version in pyproject.toml is tagged
32
+ shell: bash
33
+ run: |
34
+ version=$(grep -m1 '^version = ' pyproject.toml | cut -d'"' -f2)
35
+ echo "pyproject.toml says $version"
36
+
37
+ if ! git rev-parse -q --verify "refs/tags/v$version" >/dev/null; then
38
+ echo "::error::No tag v$version. publish.yml only runs on a pushed" \
39
+ "tag, so this version would reach main without reaching PyPI." \
40
+ "Tag it on develop first: git tag v$version && git push origin v$version." \
41
+ "A tag does not rerun this check: rerun it on the pull request afterwards."
42
+ exit 1
43
+ fi
44
+ echo "tag v$version exists"
45
+
46
+ # Only on a pull request. A squash merge rewrites the commit, so on main
47
+ # itself the tag never points at anything here and asking would fail
48
+ # every release.
49
+ #
50
+ # The tag has to be the head of this branch, not merely somewhere in its
51
+ # history. Anything pushed after the tag was cut is absent from what
52
+ # publish.yml built, so the release on PyPI would be missing code that
53
+ # main is about to advertise as part of it.
54
+ - name: The tag is the commit being merged
55
+ if: github.event_name == 'pull_request'
56
+ shell: bash
57
+ env:
58
+ HEAD_SHA: ${{ github.event.pull_request.head.sha }}
59
+ run: |
60
+ version=$(grep -m1 '^version = ' pyproject.toml | cut -d'"' -f2)
61
+ tagged=$(git rev-parse "v$version^{commit}")
62
+
63
+ if [ "$tagged" != "$HEAD_SHA" ]; then
64
+ echo "::error::Tag v$version points at $tagged, and this branch is at $HEAD_SHA. Whatever came after the tag was not in what was published, so the release would be missing it. Tag the head of this branch and publish that."
65
+ exit 1
66
+ fi
67
+ echo "tag v$version is this branch's head, $tagged"
@@ -0,0 +1,55 @@
1
+ name: Tests
2
+
3
+ # Runs on every push and pull request, and is called by publish.yml so a
4
+ # release cannot ship without passing the same checks.
5
+ on:
6
+ push:
7
+ branches: [main, develop]
8
+ pull_request:
9
+ workflow_dispatch:
10
+ workflow_call:
11
+
12
+ permissions:
13
+ contents: read
14
+
15
+ jobs:
16
+ windows:
17
+ name: pytest (Windows, ${{ matrix.label }})
18
+ runs-on: windows-latest
19
+ strategy:
20
+ fail-fast: false
21
+ matrix:
22
+ include:
23
+ - label: locked
24
+ key: locked
25
+ run: uv run --frozen pytest -q
26
+ - label: mcp 1.x
27
+ key: mcp1
28
+ run: >-
29
+ uv run --no-project --with "mcp[cli]>=1.0,<2" --with "pywin32>=306"
30
+ --with "pydantic>=2" --with "anyio>=4" --with pytest python -m pytest -q
31
+ env:
32
+ PYTHONIOENCODING: utf-8
33
+ PYTHONUTF8: "1"
34
+ UV_PYTHON: "3.12"
35
+ steps:
36
+ - uses: actions/checkout@v4
37
+ - uses: astral-sh/setup-uv@v5
38
+ with:
39
+ cache-suffix: ${{ matrix.key }}
40
+ - run: uv python install 3.12
41
+ - run: ${{ matrix.run }}
42
+
43
+ macos:
44
+ name: pytest (macOS)
45
+ runs-on: macos-latest
46
+ timeout-minutes: 20
47
+ env:
48
+ UV_PYTHON: "3.12"
49
+ steps:
50
+ - uses: actions/checkout@v4
51
+ - uses: astral-sh/setup-uv@v5
52
+ with:
53
+ cache-suffix: macos
54
+ - run: uv python install 3.12
55
+ - run: uv run --frozen pytest -q -o faulthandler_timeout=120
@@ -0,0 +1,12 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ build/
5
+ dist/
6
+ *.egg-info/
7
+ .pytest_cache/
8
+ .ruff_cache/
9
+ .DS_Store
10
+
11
+ # Documents and pictures the live check and trials make
12
+ .word-test/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ykuwai
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,198 @@
1
+ Metadata-Version: 2.5
2
+ Name: ms-word-mcp
3
+ Version: 0.1.0
4
+ Summary: Real-time Microsoft Word control on Windows and macOS: an MCP server that works in the document beside you
5
+ Project-URL: Homepage, https://github.com/ykuwai/ms-word-mcp
6
+ Project-URL: Repository, https://github.com/ykuwai/ms-word-mcp
7
+ Project-URL: Issues, https://github.com/ykuwai/ms-word-mcp/issues
8
+ Author: ykuwai
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: ai-agent,applescript,automation,com,llm,mcp,microsoft-word,word
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Operating System :: MacOS :: MacOS X
16
+ Classifier: Operating System :: Microsoft :: Windows
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Topic :: Office/Business :: Office Suites
19
+ Requires-Python: >=3.10
20
+ Requires-Dist: anyio>=4.0.0
21
+ Requires-Dist: appscript>=1.4.0; sys_platform == 'darwin'
22
+ Requires-Dist: mcp[cli]<3.0.0,>=1.23.0
23
+ Requires-Dist: pydantic>=2.0.0
24
+ Requires-Dist: pyobjc-framework-quartz>=10.0; sys_platform == 'darwin'
25
+ Requires-Dist: pywin32>=306; sys_platform == 'win32'
26
+ Description-Content-Type: text/markdown
27
+
28
+ # ms-word-mcp
29
+
30
+ An MCP server that drives a live Microsoft Word on Windows and macOS, so an AI
31
+ can write and format a document while you work in it.
32
+
33
+ > **Status:** early release (0.x). Tool names and arguments may still change.
34
+
35
+ ## What it is for
36
+
37
+ - **Working beside you.** Every write goes through a range, never through your
38
+ cursor or selection, so you can keep typing while the AI writes elsewhere in
39
+ the same document. The window scrolls to what it changed (`WORD_FOLLOW_EDITS`),
40
+ and each tool call is one Undo in Word.
41
+ - **Read back after every write.** A result says what Word actually holds now,
42
+ and lists as `warnings` whatever did not take.
43
+ - **Every script.** Latin, East Asian (Chinese, Japanese, Korean) and
44
+ complex-script (Arabic, Hebrew...) text each have their own font. East Asian
45
+ layouts get spacing in grid lines and indents in character widths, line
46
+ breaking rules, hanging punctuation and emphasis marks; lists can be
47
+ numbered in full-width digits, ①, 一, ア, 가, א, α, а and more. Vertical
48
+ text and ruby (furigana) too.
49
+ - **Styles first.** Every character and paragraph property can be set on a
50
+ style as well as on text, so a document's look is defined once.
51
+ - **Equations.** From LaTeX or UnicodeMath, built by Word's own equation
52
+ editor, numbered (1), (2)... at the right margin by fields that renumber
53
+ themselves.
54
+ - **Official sources.** Every member and constant is checked against
55
+ Microsoft's documentation
56
+ ([docs/reference](https://github.com/ykuwai/ms-word-mcp/tree/main/docs/reference)),
57
+ and what the documentation leaves unstated is measured on a real Word
58
+ ([docs/PROBES.md](https://github.com/ykuwai/ms-word-mcp/blob/main/docs/PROBES.md)).
59
+
60
+ ## Tools
61
+
62
+ The server lists three tools by default (catalog mode): `word_describe` lists
63
+ the rest a line each and gives their arguments, `word_run` runs one and
64
+ `word_run_steps` runs several in order. Set `WORD_TOOL_MODE=full` to list
65
+ every tool instead.
66
+
67
+ | Area | Tools |
68
+ |---|---|
69
+ | Word and documents | `word_get_app_info`, `word_list_documents`, `word_activate_document`, `word_open_document`, `word_create_document`, `word_save_document`, `word_save_document_as` (also PDF), `word_close_document` |
70
+ | Reading | `word_get_document_info`, `word_get_outline`, `word_get_paragraphs` |
71
+ | Writing | `word_insert_paragraphs`, `word_set_paragraph_text`, `word_delete_paragraphs`, `word_find_replace` |
72
+ | Formatting | `word_format_text`, `word_set_paragraph_format` |
73
+ | Styles | `word_apply_style`, `word_list_styles`, `word_get_style`, `word_set_style` |
74
+ | Lists | `word_apply_list`, `word_set_list_level`, `word_restart_numbering`, `word_remove_list`, `word_get_list` |
75
+ | Tables | `word_insert_table`, `word_list_tables`, `word_get_table`, `word_set_table`, `word_set_table_cells`, `word_format_table_cells`, `word_insert_table_rows`, `word_delete_table_rows`, `word_insert_table_columns` (Windows), `word_delete_table_columns`, `word_merge_table_cells`, `word_delete_table` |
76
+ | Pictures, captions, cross-references | `word_insert_picture`, `word_list_pictures`, `word_set_picture`, `word_insert_caption`, `word_list_captions`, `word_insert_cross_reference` |
77
+ | The page | `word_get_page_setup`, `word_set_page_setup` (paper, margins, columns, document grid, vertical text), `word_get_headers_footers`, `word_set_header_footer`, `word_set_page_numbers`, `word_add_ruby` (furigana) |
78
+ | Equations | `word_insert_equation`, `word_list_equations`, `word_get_equation` |
79
+ | Floating shapes and pictures | `word_insert_shape`, `word_insert_text_box`, `word_insert_line`, `word_insert_floating_picture`, `word_list_shapes`, `word_set_shape`, `word_delete_shape` |
80
+ | Footnotes and endnotes | `word_insert_note`, `word_list_notes`, `word_set_note`, `word_delete_note` |
81
+ | Hyperlinks and bookmarks | `word_insert_hyperlink`, `word_list_hyperlinks`, `word_set_hyperlink`, `word_remove_hyperlink`, `word_add_bookmark`, `word_list_bookmarks`, `word_delete_bookmark` |
82
+ | Fields and tables of contents | `word_insert_table_of_contents`, `word_insert_field`, `word_list_fields`, `word_update_fields` |
83
+ | View | `word_get_view`, `word_set_view` |
84
+ | Seeing a page | `word_get_page_image`: a picture of a page as Word lays it out, so the model can check the layout |
85
+ | Undo | `word_undo`, `word_redo` |
86
+
87
+ Every tool that works on a document takes an optional `document` argument (a
88
+ full path or file name), so a call lands in the document it names whatever
89
+ another conversation has chosen.
90
+
91
+ ## Setting it up
92
+
93
+ Requirements: Microsoft Word (Microsoft 365 or 2021+) on Windows 10/11 or
94
+ macOS, and [uv](https://docs.astral.sh/uv/).
95
+
96
+ Claude Code:
97
+
98
+ ```bash
99
+ claude mcp add word uvx ms-word-mcp
100
+ ```
101
+
102
+ Other clients (Claude Desktop, Cursor, `.mcp.json`):
103
+
104
+ ```json
105
+ {
106
+ "mcpServers": {
107
+ "word": {
108
+ "command": "uvx",
109
+ "args": ["ms-word-mcp"]
110
+ }
111
+ }
112
+ }
113
+ ```
114
+
115
+ ## Settings
116
+
117
+ | Variable | Default | What it does |
118
+ |---|---|---|
119
+ | `WORD_TOOL_MODE` | `catalog` | `catalog` lists three tools that reach the rest; `full` lists every tool. |
120
+ | `WORD_MAC_FILES_DIR` | the document's folder | macOS: where Word writes the PDF a page picture is drawn from, for a moment. By default the document's own folder (Word already has access there), or Word's own folder for a document never saved. |
121
+ | `WORD_ALLOW_ACTIVE_FIELDS` | `off` | Allow fields that reach outside the document: INCLUDETEXT, INCLUDEPICTURE, INCLUDE, LINK, IMPORT, RD, EMBED, DATABASE, DDE, DDEAUTO, MACROBUTTON, PRINT, ASK, FILLIN. Off, `word_insert_field` refuses them and `word_update_fields` leaves the ones already in a document as they are. On, Word may stop and ask you about them in a dialog of its own, and the tool waits until you answer. |
122
+ | `WORD_ALLOW_NETWORK_PATHS` | `off` | Allow files named by a network path (`\\\\server\\share\\...`). Off, they are refused: saving to one sends the document to that server, and even checking for the file connects to it with your credentials. |
123
+ | `WORD_FOLLOW_EDITS` | `on` | Scroll the document's window to each change. With a second window open on the document (View > New Window), the last one follows and the first stays where you are. |
124
+
125
+ ## Security
126
+
127
+ The server runs on your computer with your permissions and talks to one local
128
+ client over stdio; it opens no port and makes no network request of its own.
129
+
130
+ An AI using these tools can read and change any document open in Word, open
131
+ any file Word can open, and save or embed files wherever your account can
132
+ write or read. Text inside a document, a web page or another tool's answer can
133
+ try to steer the AI, so check what it does with documents you received from
134
+ someone else, and approve its tool calls where that matters.
135
+
136
+ What the server does about it:
137
+
138
+ - Macros are disabled while it opens a document or creates one from a template.
139
+ Word would otherwise run them. The document stays open with macros off.
140
+ - Fields that reach outside the document are refused and left alone unless you
141
+ set `WORD_ALLOW_ACTIVE_FIELDS` (see [Settings](#settings)).
142
+ - Network paths are refused unless you set `WORD_ALLOW_NETWORK_PATHS`.
143
+ - A new link goes to http, https, mailto or tel, or to a path relative to the
144
+ document. A link the document already has is left as it is.
145
+
146
+ What it does not do: a document opened through these tools does not get Word's
147
+ Protected View, so open only documents you would open yourself.
148
+
149
+ To report a vulnerability, see
150
+ [SECURITY.md](https://github.com/ykuwai/ms-word-mcp/blob/main/SECURITY.md).
151
+
152
+ ## On macOS
153
+
154
+ - The first call asks for permission to control Microsoft Word (System
155
+ Settings > Privacy & Security > Automation).
156
+ - Word for Mac is sandboxed: it writes without asking only inside
157
+ `~/Library/Containers/com.microsoft.Word/Data/Documents`; saving elsewhere
158
+ may make Word ask for access.
159
+ - `word_get_page_image` has Word save a PDF next to the document for a moment
160
+ and draws the page from it. For a document never saved, the PDF goes in
161
+ Word's own folder, and macOS may ask once whether the app the server runs
162
+ in may read Word's data. On Windows the page comes from Word directly.
163
+ Neither captures the screen.
164
+ - Each change is its own Undo step (Word for Mac's scripting cannot group
165
+ them), and a style can be changed but not created. Tools say so in their
166
+ results.
167
+ - Word asks you about each file outside its own folder, so `word_insert_picture`
168
+ puts a copy in Word's folder for a moment and reads it there. The first time,
169
+ macOS may ask once whether the app the server runs in may use Word's data.
170
+ - Word for Mac makes a table only in the active document, so inserting a
171
+ table brings its document forward for a moment and then gives the
172
+ previously active one back. Columns cannot be added to a table there.
173
+
174
+ ## Development
175
+
176
+ ```bash
177
+ git clone https://github.com/ykuwai/ms-word-mcp.git
178
+ cd ms-word-mcp
179
+ uv sync
180
+ uv run pytest -q # no Word needed
181
+ uv run python scripts/live_check.py # runs every tool on a real Word, in a scratch document
182
+ ```
183
+
184
+ The live check creates a document, runs the tools on it, prints PASS or FAIL
185
+ for each step, exports a PDF and closes the document. It touches no other
186
+ document.
187
+
188
+ On Windows, while a client has the server running, `uv sync` cannot replace
189
+ `.venv\Scripts\ms-word-mcp.exe`; run the tests with `uv run --no-sync`, or
190
+ stop the server first.
191
+
192
+ ## Credits
193
+
194
+ Built with [ppt-mcp](https://github.com/ykuwai/ppt-mcp)'s design.
195
+
196
+ ## License
197
+
198
+ MIT
@@ -0,0 +1,171 @@
1
+ # ms-word-mcp
2
+
3
+ An MCP server that drives a live Microsoft Word on Windows and macOS, so an AI
4
+ can write and format a document while you work in it.
5
+
6
+ > **Status:** early release (0.x). Tool names and arguments may still change.
7
+
8
+ ## What it is for
9
+
10
+ - **Working beside you.** Every write goes through a range, never through your
11
+ cursor or selection, so you can keep typing while the AI writes elsewhere in
12
+ the same document. The window scrolls to what it changed (`WORD_FOLLOW_EDITS`),
13
+ and each tool call is one Undo in Word.
14
+ - **Read back after every write.** A result says what Word actually holds now,
15
+ and lists as `warnings` whatever did not take.
16
+ - **Every script.** Latin, East Asian (Chinese, Japanese, Korean) and
17
+ complex-script (Arabic, Hebrew...) text each have their own font. East Asian
18
+ layouts get spacing in grid lines and indents in character widths, line
19
+ breaking rules, hanging punctuation and emphasis marks; lists can be
20
+ numbered in full-width digits, ①, 一, ア, 가, א, α, а and more. Vertical
21
+ text and ruby (furigana) too.
22
+ - **Styles first.** Every character and paragraph property can be set on a
23
+ style as well as on text, so a document's look is defined once.
24
+ - **Equations.** From LaTeX or UnicodeMath, built by Word's own equation
25
+ editor, numbered (1), (2)... at the right margin by fields that renumber
26
+ themselves.
27
+ - **Official sources.** Every member and constant is checked against
28
+ Microsoft's documentation
29
+ ([docs/reference](https://github.com/ykuwai/ms-word-mcp/tree/main/docs/reference)),
30
+ and what the documentation leaves unstated is measured on a real Word
31
+ ([docs/PROBES.md](https://github.com/ykuwai/ms-word-mcp/blob/main/docs/PROBES.md)).
32
+
33
+ ## Tools
34
+
35
+ The server lists three tools by default (catalog mode): `word_describe` lists
36
+ the rest a line each and gives their arguments, `word_run` runs one and
37
+ `word_run_steps` runs several in order. Set `WORD_TOOL_MODE=full` to list
38
+ every tool instead.
39
+
40
+ | Area | Tools |
41
+ |---|---|
42
+ | Word and documents | `word_get_app_info`, `word_list_documents`, `word_activate_document`, `word_open_document`, `word_create_document`, `word_save_document`, `word_save_document_as` (also PDF), `word_close_document` |
43
+ | Reading | `word_get_document_info`, `word_get_outline`, `word_get_paragraphs` |
44
+ | Writing | `word_insert_paragraphs`, `word_set_paragraph_text`, `word_delete_paragraphs`, `word_find_replace` |
45
+ | Formatting | `word_format_text`, `word_set_paragraph_format` |
46
+ | Styles | `word_apply_style`, `word_list_styles`, `word_get_style`, `word_set_style` |
47
+ | Lists | `word_apply_list`, `word_set_list_level`, `word_restart_numbering`, `word_remove_list`, `word_get_list` |
48
+ | Tables | `word_insert_table`, `word_list_tables`, `word_get_table`, `word_set_table`, `word_set_table_cells`, `word_format_table_cells`, `word_insert_table_rows`, `word_delete_table_rows`, `word_insert_table_columns` (Windows), `word_delete_table_columns`, `word_merge_table_cells`, `word_delete_table` |
49
+ | Pictures, captions, cross-references | `word_insert_picture`, `word_list_pictures`, `word_set_picture`, `word_insert_caption`, `word_list_captions`, `word_insert_cross_reference` |
50
+ | The page | `word_get_page_setup`, `word_set_page_setup` (paper, margins, columns, document grid, vertical text), `word_get_headers_footers`, `word_set_header_footer`, `word_set_page_numbers`, `word_add_ruby` (furigana) |
51
+ | Equations | `word_insert_equation`, `word_list_equations`, `word_get_equation` |
52
+ | Floating shapes and pictures | `word_insert_shape`, `word_insert_text_box`, `word_insert_line`, `word_insert_floating_picture`, `word_list_shapes`, `word_set_shape`, `word_delete_shape` |
53
+ | Footnotes and endnotes | `word_insert_note`, `word_list_notes`, `word_set_note`, `word_delete_note` |
54
+ | Hyperlinks and bookmarks | `word_insert_hyperlink`, `word_list_hyperlinks`, `word_set_hyperlink`, `word_remove_hyperlink`, `word_add_bookmark`, `word_list_bookmarks`, `word_delete_bookmark` |
55
+ | Fields and tables of contents | `word_insert_table_of_contents`, `word_insert_field`, `word_list_fields`, `word_update_fields` |
56
+ | View | `word_get_view`, `word_set_view` |
57
+ | Seeing a page | `word_get_page_image`: a picture of a page as Word lays it out, so the model can check the layout |
58
+ | Undo | `word_undo`, `word_redo` |
59
+
60
+ Every tool that works on a document takes an optional `document` argument (a
61
+ full path or file name), so a call lands in the document it names whatever
62
+ another conversation has chosen.
63
+
64
+ ## Setting it up
65
+
66
+ Requirements: Microsoft Word (Microsoft 365 or 2021+) on Windows 10/11 or
67
+ macOS, and [uv](https://docs.astral.sh/uv/).
68
+
69
+ Claude Code:
70
+
71
+ ```bash
72
+ claude mcp add word uvx ms-word-mcp
73
+ ```
74
+
75
+ Other clients (Claude Desktop, Cursor, `.mcp.json`):
76
+
77
+ ```json
78
+ {
79
+ "mcpServers": {
80
+ "word": {
81
+ "command": "uvx",
82
+ "args": ["ms-word-mcp"]
83
+ }
84
+ }
85
+ }
86
+ ```
87
+
88
+ ## Settings
89
+
90
+ | Variable | Default | What it does |
91
+ |---|---|---|
92
+ | `WORD_TOOL_MODE` | `catalog` | `catalog` lists three tools that reach the rest; `full` lists every tool. |
93
+ | `WORD_MAC_FILES_DIR` | the document's folder | macOS: where Word writes the PDF a page picture is drawn from, for a moment. By default the document's own folder (Word already has access there), or Word's own folder for a document never saved. |
94
+ | `WORD_ALLOW_ACTIVE_FIELDS` | `off` | Allow fields that reach outside the document: INCLUDETEXT, INCLUDEPICTURE, INCLUDE, LINK, IMPORT, RD, EMBED, DATABASE, DDE, DDEAUTO, MACROBUTTON, PRINT, ASK, FILLIN. Off, `word_insert_field` refuses them and `word_update_fields` leaves the ones already in a document as they are. On, Word may stop and ask you about them in a dialog of its own, and the tool waits until you answer. |
95
+ | `WORD_ALLOW_NETWORK_PATHS` | `off` | Allow files named by a network path (`\\\\server\\share\\...`). Off, they are refused: saving to one sends the document to that server, and even checking for the file connects to it with your credentials. |
96
+ | `WORD_FOLLOW_EDITS` | `on` | Scroll the document's window to each change. With a second window open on the document (View > New Window), the last one follows and the first stays where you are. |
97
+
98
+ ## Security
99
+
100
+ The server runs on your computer with your permissions and talks to one local
101
+ client over stdio; it opens no port and makes no network request of its own.
102
+
103
+ An AI using these tools can read and change any document open in Word, open
104
+ any file Word can open, and save or embed files wherever your account can
105
+ write or read. Text inside a document, a web page or another tool's answer can
106
+ try to steer the AI, so check what it does with documents you received from
107
+ someone else, and approve its tool calls where that matters.
108
+
109
+ What the server does about it:
110
+
111
+ - Macros are disabled while it opens a document or creates one from a template.
112
+ Word would otherwise run them. The document stays open with macros off.
113
+ - Fields that reach outside the document are refused and left alone unless you
114
+ set `WORD_ALLOW_ACTIVE_FIELDS` (see [Settings](#settings)).
115
+ - Network paths are refused unless you set `WORD_ALLOW_NETWORK_PATHS`.
116
+ - A new link goes to http, https, mailto or tel, or to a path relative to the
117
+ document. A link the document already has is left as it is.
118
+
119
+ What it does not do: a document opened through these tools does not get Word's
120
+ Protected View, so open only documents you would open yourself.
121
+
122
+ To report a vulnerability, see
123
+ [SECURITY.md](https://github.com/ykuwai/ms-word-mcp/blob/main/SECURITY.md).
124
+
125
+ ## On macOS
126
+
127
+ - The first call asks for permission to control Microsoft Word (System
128
+ Settings > Privacy & Security > Automation).
129
+ - Word for Mac is sandboxed: it writes without asking only inside
130
+ `~/Library/Containers/com.microsoft.Word/Data/Documents`; saving elsewhere
131
+ may make Word ask for access.
132
+ - `word_get_page_image` has Word save a PDF next to the document for a moment
133
+ and draws the page from it. For a document never saved, the PDF goes in
134
+ Word's own folder, and macOS may ask once whether the app the server runs
135
+ in may read Word's data. On Windows the page comes from Word directly.
136
+ Neither captures the screen.
137
+ - Each change is its own Undo step (Word for Mac's scripting cannot group
138
+ them), and a style can be changed but not created. Tools say so in their
139
+ results.
140
+ - Word asks you about each file outside its own folder, so `word_insert_picture`
141
+ puts a copy in Word's folder for a moment and reads it there. The first time,
142
+ macOS may ask once whether the app the server runs in may use Word's data.
143
+ - Word for Mac makes a table only in the active document, so inserting a
144
+ table brings its document forward for a moment and then gives the
145
+ previously active one back. Columns cannot be added to a table there.
146
+
147
+ ## Development
148
+
149
+ ```bash
150
+ git clone https://github.com/ykuwai/ms-word-mcp.git
151
+ cd ms-word-mcp
152
+ uv sync
153
+ uv run pytest -q # no Word needed
154
+ uv run python scripts/live_check.py # runs every tool on a real Word, in a scratch document
155
+ ```
156
+
157
+ The live check creates a document, runs the tools on it, prints PASS or FAIL
158
+ for each step, exports a PDF and closes the document. It touches no other
159
+ document.
160
+
161
+ On Windows, while a client has the server running, `uv sync` cannot replace
162
+ `.venv\Scripts\ms-word-mcp.exe`; run the tests with `uv run --no-sync`, or
163
+ stop the server first.
164
+
165
+ ## Credits
166
+
167
+ Built with [ppt-mcp](https://github.com/ykuwai/ppt-mcp)'s design.
168
+
169
+ ## License
170
+
171
+ MIT
@@ -0,0 +1,12 @@
1
+ # Security
2
+
3
+ Please report a vulnerability privately, through
4
+ [GitHub's private vulnerability reporting](https://github.com/ykuwai/ms-word-mcp/security/advisories/new),
5
+ rather than in a public issue. Say what an attacker can do, and how to
6
+ reproduce it.
7
+
8
+ Only the latest release and the `main` branch are supported. The project is
9
+ pre-release, so fixes land there first.
10
+
11
+ What the server protects against, and what it leaves to you, is in the
12
+ [Security section of the README](README.md#security).