KitchenSink4Word

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.1k 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.

Tool	Operations	Approx. tokens	What it covers
word_read	24	1,368	Read text, an anchored document view, the outline and tables; find text; list elements; read styles, comments, tracked changes, headers and footers, properties and protection; validate and diagnose; word counts and structured diff; citation checks; get_workflows, get_server_info and Word status
word_edit	9	1,031	Insert, change and delete paragraphs, find and replace across split runs, batch edits with apply_edits, breaks, anchors and verified redaction
word_format	6	620	Styles, character and paragraph formatting, heading levels and publication formats
word_structure	15	1,025	Headers and footers, sections, page numbers, lists and numbering, tables (create, edit, restructure, sort, import), chapter headers and moving sections
word_media	12	906	Images, charts, equations, text boxes, hyperlinks, fields, content controls and form fields
word_review	7	787	Threaded comments, accepting and rejecting tracked changes, switching Track Changes on or off in a closed file, marking edits made with Track Changes off against an earlier copy, anonymizing for peer review and restoring, submission preparation
word_references	13	1,032	Footnotes and endnotes, captions, tables of contents and figures, index entries, bookmarks, cross-references, Word-native citations and bibliography, Zotero search and cite, citation style conversion
word_document	15	1,030	New and copied documents, backups, properties and embedded fonts, inserting and splitting documents, templates and mail merge, front matter, protection, watermarks, accessibility fixes, table export
word_app	14	1,070	Drives a local Word: save a document open in Word, edit it live, toggle track changes, refresh fields, PDF import and export, compare and combine, proofing, readability, open-clean validation. Needs Windows with Word. Also updates the server when you ask (update_now) and turns update notices on or off (update_notices)
word_help	0	213	The arguments and a worked example for any operation, and an explanation of the location object
All ten	115	9,082	Loaded once at the start; nothing to switch on later

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.

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."

Variable	Effect
KS4W_READ_ONLY	1 lists only the operations that read, so nothing can change a file
KS4W_FORBID	A comma-separated list of tool or operation names to remove from the tool list and from word_help; a call to one refuses NOT_AVAILABLE. An unknown name stops startup. word_app here closes every route to your running Word, including the live routes of other operations
KS4W_ALLOWED_ROOTS	Path sandbox: folders separated by ; on Windows (: elsewhere)
KS4W_AUTHOR	Who tracked changes and comments are signed by when a call names no author: user (the default) signs with your own Office user name, the one Word uses (never an email address: the Windows sign-in name stands in for one); assistant signs "AI Assistant via KS4Word", and a call can ask for that name itself with author="assistant" whatever the setting is. Any other author in a call wins, except an email address, which is never written into a document: the default signs instead and the answer says so. In a document open in Word, Word signs edits with its own user name
KS4W_CALL_TIMEOUT_S	Wall-clock bound for one call, in seconds (default 300, from 1 to 3600)
KS4W_MAX_CALL_TIMEOUT_S	Ceiling for operations that declare a longer bound of their own, such as the Word-driven ones (default 900, from 1 to 3600)
KS4W_MAX_OUTPUT_CHARS	Ceiling on the size of one reply, in characters (default 80,000, minimum 2,000). A longer reply is cut and says what was cut and how to continue
KS4W_UPDATE_CHECK	off turns the update check off completely (the older KS4W_NO_UPDATE_CHECK=1 also works)
KS4W_UPDATE_NOTICES	off turns update notices off; on turns them back on after you turned them off

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.

Dual-mode operation (file + live)	Live-mode notes
apply_edits	one COM undo group; markdown lists/pipe tables in insert ops refuse up front with a close-the-file hint; replace verifies matched text in the live range; all other index-addressed ops run the snapshot staleness guard against the last saved state
delete_paragraphs	section-break/field-crossing ranges refuse; range={} location endpoints run the snapshot staleness guard
find_text	plain queries, 500-match cap; formatting mode and include_textboxes file-mode only
format_text	formatting mode routes live; case mode file-mode only (live='force' refuses); range={} locations run the snapshot staleness guard
get_comments	same shape
get_document_info	same key names; adds words/track_revisions, omits part list
get_outline	same flat-list shape
get_text	body shape identical; include_textboxes/textbox modes file-mode only
insert_paragraphs	heading_level maps to built-in Heading styles by numeric constant (outline-based docs get direct outline levels); inherit_format/copy_format_from file-mode only; text-selector locations run the snapshot staleness guard
search_and_replace	plain items route live (255-char finds handled); preview and find_formatting modes are file-mode only (find_formatting with live='force' refuses)
set_cells	plain text cells; vertical merges refuse live
set_paragraph_format	shading/borders/tab_stops keys refuse live (XML-level); raw indices keep the v1 index-trust contract
set_paragraph_text	expect guard honored; tracked-revision paragraphs refuse; text-selector locations run the snapshot staleness guard
word_count	Word's own statistics engine; exclusions mode file-mode only

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.

If you called	It now lives in
get_text, get_document_view, find_text, list_elements, get_headers_footers, get_document_info, com_word_status, validate, diagnose_document, get_workflows, get_styles, get_outline, get_table, get_comments, get_tracked_changes, get_server_info, structured_diff, get_paragraph_format, word_count, get_revision_report, comment_report, get_protection, detect_citation_system, parse_references	word_read
insert_paragraphs, search_and_replace, delete_paragraphs, insert_break, apply_edits, delete_element, stamp_anchors, set_paragraph_text, redact_text	word_edit
define_style, apply_style, format_text, set_paragraph_format, change_heading_level, apply_manuscript_format	word_format
set_header_footer, set_section_properties, insert_list, create_table, set_table_properties, set_cells, delete_table, modify_table_structure, format_cells, sort_table, import_table, set_list_numbering, set_page_numbers, setup_chapter_headers, move_section	word_structure
insert_image, insert_field, set_image, export_images, insert_chart, set_chart_data, insert_equation, set_textbox_text, insert_hyperlink, insert_content_control, set_content_control, set_form_fields	word_media
manage_comment, resolve_revisions, anonymize_for_review, deanonymize_document, prepare_for_submission	word_review
manage_note, insert_caption, insert_reference_list, insert_bookmark, convert_notes, insert_cross_reference, mark_index_entry, insert_citation, insert_zotero_citation, search_zotero_library, manage_source, set_bibliography_style, convert_citation_style	word_references
insert_document, copy_document, create_document, manage_backups, set_document_properties, split_document, copy_table, apply_template, fill_template, mail_merge, assemble_front_matter, set_document_protection, set_watermark, fix_accessibility, export_table	word_document
com_save_document, live_insert_at_cursor, live_set_track_changes, com_refresh_fields, com_validate_opens_clean, com_multi_document, com_import_pdf, com_export_pdf, live_scroll_to, live_repair, com_proofing_errors, com_readability_statistics	word_app
enable_tools, disable_tools	Gone. Every operation is available from the start

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,384 tests. 96 of them drive a real Word window, and 133 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.

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 licensing@kitchensink4.ai.

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.