KitchenSink4Word

[图片] KitchenSink4Word

[Tests] [PyPI] [License: AGPL-3.0]

Edit Word documents with your AI assistant: tracked changes, citations, templates, and live edits in an open document.

Your AI gets 231 actions in Word, a backup before every change, and a question instead of a guess when your request could mean more than one place.

KitchenSink4Word is an MCP server that lets Claude Code, the Codex CLI, Copilot CLI, Claude Desktop and other local MCP clients read and edit .docx files. It can also work on a document while it is open in Microsoft Word, so you watch the changes arrive. This is the free Community edition, licensed under the AGPL-3.0.

Product page · llms.txt · Changelog

Platform: Windows. Editing files works without Word installed. Live editing and the Word-powered features (PDF import and export, document compare, proofing, field refresh) need Microsoft Word.

Install

The package needs Python 3.12 or newer. Run the commands below in PowerShell or a terminal, not in an AI chat.

Claude Code or Codex CLI. Install uv, run the line for your app, and start a new session:

claude mcp add word -s user -- uvx kitchensink4word

codex mcp add word -- uvx kitchensink4word

Claude Desktop. Install uv and restart Claude Desktop. Download the .mcpb file from the latest release, then open Settings > Extensions > Advanced settings > Install extension and choose the file. The first launch downloads the Python package, so it needs a network connection.

Any other local MCP client. Use uvx as the command and kitchensink4word as its argument, or install the package and run kitchensink4word as the server command:

pip install kitchensink4word

Installing the package by itself does not connect it to an AI app; add it as a local MCP server in your client's settings.

What it can do

• Revise a report while it stays open in Word, with each edit visible as it lands.
• Read, accept and reject tracked changes, write edits as tracked changes, and work through reviewer comments.
• Fill templates, assemble chapter files into one document, and run mail merges.
• Build and format tables, lists, headings, sections and page layouts.
• Insert citations, bibliographies, footnotes, endnotes, captions and cross-references, including Zotero library citations.
• Check formatting, accessibility and document structure before you hand a file over.
• Compare two versions of a document, redact selected text, and import or export PDF through Word.

In total the server offers 115 operations in 10 tools, 231 counting each action an operation can take (for example each kind of note or table change). The whole tool list costs about 9.2k tokens of your AI's working memory at startup. Figures come from scripts/measure_surface.py and scripts/count_operations.py.

Highlights

• Table columns through merged cells. Inserting or deleting a column works correctly when the table has horizontally or vertically merged cells.
• Bulk edits in one call. Twenty cell edits are one set_cells call, not twenty round trips.
• Real tracked changes. Edit tools accept track and an author and produce Word revisions the recipient can accept or reject. With no author named, changes and comments are signed with your Office user name, the one your own Word uses, and the result's author_source says where the name came from. To sign one call as the assistant instead, pass author="assistant", which signs "AI Assistant via KS4Word".
• Word-native compare. com_multi_document with action="compare" produces a redline between two versions.
• Built not to corrupt. Saves are atomic and validated, the previous version is backed up before every change, and anything the call does not touch (equations, text boxes, content controls) passes through byte for byte. A file that is open in Word is refused with a clear message instead of a hang.
• Find and replace across split runs. Matches work even when Word has broken the text into many runs, and per-character formatting is preserved. User regular expressions run with a timeout.
• Edits you can aim. Text that matches more than once is refused with every candidate listed, so the wrong paragraph is never edited silently, and a refusal carries the next call to make.

The ten tools and context cost

The server lists ten tools, all from the first message, with nothing to switch on. Every tool except word_help takes an op (the operation to run) and args (its arguments, including the file_path of the .docx). word_help returns the arguments and a worked example for any operation, and an argument an operation does not define is refused rather than ignored. Token figures count the full tools/list entry the client receives and come from scripts/measure_surface.py.

For a recipe, ask your AI to call get_workflows. It lists 13 tasks, each with the right tool and operation for every step. Clients that load tool schemas on first use, such as Claude Code, pay close to nothing until a tool is called. The server's own instructions add about 500 tokens to the figures above.

Administrators who want a narrower server can set KS4W_READ_ONLY=1, which lists only the operations that read, or list the tools or operations to remove in KS4W_FORBID (see Configuration). What is removed no longer counts toward the cost.

Fewer permission prompts: in Claude Desktop's tool permissions for this server, set the read-only tools to Always Allow. They cannot change anything. Leave the editing tools on Ask.

Safety model

• Before every change to a closed file, the current version is copied into a hidden .ks4w-backups/ folder next to the document. Each document keeps two copies: prev.docx (the state before the most recent change) and anchor.docx (the state at the start of the session, refreshed after an hour of inactivity). Storage stays at about two copies per document no matter how many edits you make. manage_backups lists, restores and purges them, and a restore can itself be undone.
• Edits to a document that is open in Word are not part of this backup system. Word's own AutoRecover and undo cover the open document.
• Saves are atomic and validated. If an operation fails, the original file is left exactly as it was.
• Changes to the same file are serialized, within one server and across server processes, so parallel calls cannot overwrite each other.
• Deleting content that holds footnote references removes the orphaned notes, and validate checks integrity in both directions. Paragraph deletion refuses ranges that would cut a field such as a TOC in half or remove a section break by accident.
• Exclude .ks4w-backups/ from cloud sync (OneDrive, Dropbox, Google Drive). The backup files change with every edit, and sync clients can hold locks that slow saves down.
• Protection is honored. A document with an editing restriction, and a file with Windows' read-only attribute, are not edited around: the write refuses with PROTECTED and the file is left exactly as it was. set_document_protection and manage_backups stay available on a protected document, so you can lift the restriction or restore a backup.
• Snapshots before destructive operations. redact_text, resolve_revisions, prepare_for_submission, anonymize_for_review and set_document_protection keep a labeled snapshot of the file as it was, and manage_backups restores it by label.
• Refusals instead of guesses. Ambiguous targets are refused with every candidate listed, an unknown style, key or cell address is refused by name, and a call that would delete a header's pictures or tables is refused unless you say so. Each refusal is structured ({ok: false, error: {code, message, hint}}) and names the next call to make.
• Word stays yours. An encrypted file is refused before the server's hidden Word starts, so no password dialog lands on your desktop. The server ends a Word process only if it started that process itself and can prove it, never by program name, and a call that runs past its time limit answers TIMEOUT and, for a file edit, saves nothing.
• Redaction and anonymization are not guaranteed. redact_text removes the text you name from every place it can safely reach, then re-reads the saved file and reports anything left. anonymize_for_review masks self-citations and author metadata and flags the rest for you. Neither can see text inside pictures or scans, and neither can know a name you did not give it, such as initials or a nickname. Check anything sensitive yourself before you share or submit it. For legal or regulated redaction, redact the final PDF with a dedicated tool.

Privacy

The server runs on your computer. KitchenSink4AI never receives your files or usage data. Your AI app may send prompts, file contents and tool results to its own provider under that app's settings and terms. The update check described below contacts PyPI at most once a week and sends only the package name and the installed version. Choosing Update now downloads the new version from PyPI, or the new bundle from GitHub for Claude Desktop. The server's startup banner is switched off, so the framework it runs on makes no version check of its own. The Privacy Policy covers the product, purchases and support.

Configuration

Launch settings are environment variables in the server's configuration. They are read once at start and never change afterward, and no tool call, argument or prompt can change them. A setting the server cannot parse stops it at start with one readable line that ends with "The server did not start."

Settings from earlier versions are handled for you. An old default (KS4W_MODE=lite, full or everything, KS4W_PACK_POLICY=auto, KS4W_ALL_TOOLS, KS4W_LOCK_TOOLS off) is ignored with a one-line notice on stderr, and the status report lists it. A setting that locked the tools (KS4W_PACK_POLICY=locked, KS4W_LOCK_TOOLS on or a KS4W_MODE list of tool groups) stops the start with a message naming what to use instead: KS4W_READ_ONLY or KS4W_FORBID.

Update check and update notices. At most once a week, after you use a tool, the server asks PyPI in the background which version of kitchensink4word is newest. The request names only the package and the installed version and contains no documents, file names or identifiers. When a newer version exists and the server runs through uvx or the Claude Desktop extension, your AI app shows a short notice with Update now and Not now, where the app supports one. Otherwise your AI mentions the new version once and offers to update. It never downloads or installs a new version unless you choose Update now in its notice or ask your AI to update it. To turn notices off, ask your AI to turn off KitchenSink4Word update notices; KS4W_UPDATE_NOTICES=off turns them off everywhere, and KS4W_UPDATE_CHECK=off turns the check off completely (the older KS4W_NO_UPDATE_CHECK=1 also works). The setting is kept in the server's own state folder, so it survives updates.

Sandboxing (optional). Set KS4W_ALLOWED_ROOTS to a list of folders separated by ; on Windows (: elsewhere), for example %USERPROFILE%\Documents;D:\Work. Every path the server reads or writes must then resolve inside one of them. The check runs on canonical paths, so ..\ traversal, symbolic links and junctions, 8.3 short names, extended-length prefixes, case tricks and lookalike folder names (Documents2 next to an allowed Documents) are all caught. Network (UNC) paths are refused unless an allowed root is itself a UNC path that contains them. A blocked call returns a typed error naming the path and the allowed roots before any file is opened. We recommend it whenever the server handles requests you do not fully trust.

Live editing in Word

Which operations work on a document that is open in Word. Dual-mode operations auto-route (live='auto'); everything else refuses with DOCUMENT_LOCKED until the file is closed. Word COM calls within one server process are serialized. Live calls and passwordless save or close also use a machine-local cross-process lock; a concurrent caller receives APP_BUSY before touching Word and nothing is queued. Live edits stay unsaved until com_save_document; get_workflows(task='live-editing') explains the model.

Live-only operations (need the document open): live_insert_at_cursor, live_repair, live_scroll_to, live_set_track_changes.
COM tier (drive the Word application, open or closed): com_export_pdf, com_import_pdf, com_multi_document, com_proofing_errors, com_readability_statistics, com_refresh_fields, com_save_document, com_validate_opens_clean, com_word_status.
Open-document reader: get_document_view (reads the last SAVED state and says so).

Every other operation that reads or changes a document's file is file-only: it refuses while the document is open (close it, or use com_save_document with close=true).

Known limits

• Live regular-expression replacements skip matches that sit after complex fields in the same story, because Word's character offsets drift there. The number skipped is reported, and a plain-text find still works.
• Live set_cells refuses tables with vertically merged cells. The file-based tool handles them; close the document first.
• Live tracked-change attribution follows Word: if Word is signed in to an Office account, revisions are attributed to that account. Results report the author Word actually used.
• Table of contents and caption-list page numbers need a field update. Word does it the next time the file opens, or call com_refresh_fields.
• A content control bound to the document's custom XML shows the text saved in the file; Word fills it from the stored data when the file opens, so the two can differ.
• A few operations slow down sharply on extreme documents. retrack_changes on a paragraph of 100,000 characters or more with a paragraph added after it takes over a minute and grows quickly with the length, and set_header_footer on a document with a thousand sections takes minutes. A call that reaches the time limit stops with an error and leaves the file unchanged.
• In a document on disk, built-in styles are found by the English names Word keeps in every language, such as heading 2 or Caption, or by the document's own style IDs. A name in another language, such as Überschrift 2, is refused, and the refusal lists the style IDs the document has. On a document open in Word, a style name goes to Word as given, so a Word installed in another language may need its own name for the style.

Heuristic tools. convert_citation_style, anonymize_for_review, validate(checks=["defined_terms"]) and the text-reference scan in validate(checks=["cross_references"]) are heuristic. Each returns a list of what it could not handle with confidence, so review that list rather than trusting the result blindly.

Upgrading from 2.x

Version 3.0 regroups the 112 flat tools of 2.2.x into the ten tools above. Every operation keeps its name except enable_tools and disable_tools, which are gone, but you now call it as an operation of a tool: word_edit with op="insert_paragraphs" instead of a tool named insert_paragraphs. The install commands, the package name and the commands word-mcp and kitchensink4word are unchanged.

A few arguments changed spelling, and the old spellings still work: after_anchor is now after_text and anchor_text is now at_text, set_document_protection takes read_only and tracked_changes, and list and page-number formats are snake_case (lower_roman). stamp_anchors moved from get_document_view to its own word_edit operation. Some behavior changed too: format_text and the inserters that locate by text refuse an ambiguous match until you pick an occurrence, tracked changes and comments are signed with your Office user name unless you name an author, and a protected document refuses writes. docs/surface_map.md lists every 2.2.1 tool beside its replacement, and the migrate-from-v2 recipe in get_workflows gives your AI the same map, including the changed arguments. The changelog lists everything else.

Upgrading from 1.x

Every 1.x tool name changed in 2.0, when 189 tools were consolidated into 110 that cover every earlier capability. Read the migration guide first; it maps each old name to its 2.x name, and docs/surface_map.md then maps that name to its tool and operation in 3.0. get_workflows("migrate-from-v1") returns the first map inside a session.

Testing

The suite has 4,525 tests. 96 of them drive a real Word window, and 135 start a private hidden Word of their own; they run only on Windows with Word installed. Tests that need sample documents generate structurally equivalent synthetic files with tests/make_corpus.py, so the rest of the suite runs on any machine and on every pull request. tests/word_validator.py opens each output in an invisible Word and fails on any repair prompt.

To run the suite without Word:

pytest tests -m "not live and not hidden_word"

Reporting problems

Please open an issue with the tool name, the call you made, what happened and what you expected. Ask your AI to run get_server_info and paste the output; it is designed to be safe to share. Please do not attach documents that contain anything private. For security issues, follow SECURITY.md instead.

Business edition

The Business edition pairs these tools with a Windows installer, a signed update channel and support under the Business terms. Update checks tell you when a covered release is available, and nothing installs on its own. See pricing. The Community edition stays free under the AGPL, including business use that meets its terms.

Contributing

Bug reports, fixes, tests and documentation are welcome. See CONTRIBUTING.md; first-time contributors agree to the Contributor License Agreement.

Review AI-assisted work

AI assistants make mistakes, and so does software. Have a person review any document an AI has edited before you rely on it, share it or submit it, and keep the backups until you have. KitchenSink4Word is provided under the AGPL-3.0 without any warranty, and, to the extent the law allows, its authors and KitchenSink4AI are not liable for the results of using it; sections 15 and 16 of the license govern.

License

KitchenSink4Word is dual-licensed.

• AGPL-3.0. Free for anyone, including businesses, for any use that complies with the AGPL. Its terms include sharing your source code, with your modifications, when you distribute the software or make it available over a network.
• Commercial license. For organizations that want to build KitchenSink4Word into their own products or services without the AGPL's source-sharing obligations. Contact [email protected].

Copyright (c) 2026 Alvut Consulting, LLC. KitchenSink4AI is a product line of Alvut Consulting, LLC. KitchenSink4AI tools are built with the help of AI coding assistants, and every release goes through the full test suite before it ships.

Not affiliated with, endorsed by, or sponsored by Microsoft Corporation. Microsoft and Word are trademarks of the Microsoft group of companies. GitHub and Copilot are trademarks of the Microsoft group of companies. Claude is a trademark of Anthropic. Codex and OpenAI are trademarks of OpenAI. All other trademarks are the property of their respective owners.