Edit your Word, PowerPoint and Excel files and fill company templates without breaking formatting
Model Context Protocol (MCP) Server: io.github.ilia-sokolov/officeagent
This MCP server, io.github.ilia-sokolov/officeagent, creates and edits Word, PowerPoint, and Excel files using typed plans and safe previews. It is implemented around document automation needs and is associated with the Model Context Protocol (MCP) ecosystem.
๐ ๏ธ Key Features
Typed plans for file operations
Safe previews during document changes
Supports Word, PowerPoint, and Excel workflows
๐ Use Cases
Automating edits to DOCX, PPTX, and Excel documents
Applying tracked changes as part of document editing workflows
Building document-automation pipelines using C#/.NET
โก Developer Benefits
Designed for .NET (dotnet) usage and OpenXML-based document formats
Provides an MCP integration surface for agent-driven document automation
Includes topic-aligned support for tracked-changes workflows
โ ๏ธ Limitations
The available description does not specify supported OS, authentication, or performance constraints.
word documentssharepointchange trackingdocument editingoffice automation
OfficeAgent.NET lets an AI agent or a .NET application edit your own Word, PowerPoint
and Excel files without breaking them:
Fill your company's Word template: content controls, bookmarks and repeating table
rows, returned as the same file with its styles, numbering, headers and comments intact.
Build slides on your own PowerPoint template: new slides on the template's own
layouts, with named shapes, tables, charts and pictures filled and the logo and fonts
left alone.
Change clauses, prices or dates as real tracked changes that Word can accept or reject.
Every change is a typed plan that is previewed first, and if any check fails nothing is
written. It is built on Microsoft's
Open XML SDK and runs without
Office installed.
Use it from
Start with
Claude Code, Codex, Cursor or any MCP client, with no .NET installed
uvx officeagent-mcp --stdio, pointed at a folder as in Try a Word edit
An Office Open XML file is a package of related XML parts. A small change
can affect runs, styles, numbering, comments, content controls, or revision
markup. OfficeAgent.NET handles that document-specific work. The model works
with structured document data and JSON-serialisable operations such as "replace
this clause as a tracked change" or "add a row to this table."
The same engine is available in three forms:
an MCP server for agents that support the Model Context Protocol;
tools for Microsoft Agent Framework and Microsoft.Extensions.AI;
a .NET API for applications that want to control the workflow directly.
It supports Word .docx, PowerPoint .pptx, and Excel .xlsx; one client routes
each document to the module that handles it. See Scope and limitations before choosing
it for a workflow that depends on Office's layout or calculation engine.
What you can build
Area
Supported workflows
Word creation and editing
Create .docx files, blank or from a .docx or .dotx template; inspect and change text, paragraphs, tables, images, styles, content controls, headers, footers, notes, page setup, and document properties; replace a picture and keep its frame
Word review
Read and manage comments, preserve or resolve review state, set one revision identity per plan, and record supported edits as tracked revisions, marking only the changed words if you choose
PowerPoint creation and editing
Build decks, blank or from a .pptx or .potx template, or update them with slides on the template's own layouts, text, tables, native editable charts, images, media, notes, comments, sections, transitions, and animations
Excel inspection and editing
Inspect worksheets, tables, and bounded ranges; read cells as Excel displays them; find raw or displayed values; set cells and formulas; append table rows; manage cell notes
Report refresh
Update the numbers, tables and charts of a Word report or PowerPoint deck from an Excel workbook, through links the document keeps for next month
Translation and bulk edits
Rewrite a paragraph in another language and keep its formatting; change every match of a phrase; apply one plan to up to 100 documents
Template generation
Find the organization's templates, bind unique Word content-control tags or PowerPoint shape names, expand repeating Word table rows, and create bounded batches with one receipt per output
Word comparison
Compare supported free-body paragraph text read-only and produce a snapshot-bound native redline plan only when all other package content is unchanged
Agent and application integration
Use MCP over stdio or HTTP, Microsoft Agent Framework tools, or the direct .NET API, with SHA-256 apply receipts and host-supplied audit actors
Document access
Work with bounded filesystem roots, SharePoint, iManage Work, Google Drive, Box, Azure Blob Storage, Amazon S3, in-memory sessions, or self-contained inline content; list a connection's documents and templates
This small workflow demonstrates that OfficeAgent can change an existing OOXML file
without flattening its structure. It uses tracked changes because the result is easy to
verify in Word; review is one part of the broader document operation set.
Install the exact server version documented by this release:
Make a folder for the agent to work in and download the
sample contract into it โ a fictional services
agreement with a clause to change, a table, an open comment, and a pending redline:
For this review-specific workflow, you can optionally install the
word-document-review skill before starting the client.
Then ask:
In services-agreement.docx, change the payment terms from thirty days to forty-five days.
Expected result when the client invokes OfficeAgent correctly: apply_plan reports
writeOutcome: "committed" and returns an output id, and clause 3 reads forty-five days
as a tracked change you can accept or reject. Open that output in Word and verify the change.
The regression test also verifies that the sample's existing table, comment, earlier payment
redline, and heading remain present with their tested XML semantics. It does not claim byte-for-byte
identity for every unrelated OOXML part; see the bounded preservation evidence.
If the agent did not call apply_plan, or if writeOutcome is not committed, do not report
the edit as complete. For unknown or writtenNotRegistered, preserve possibleOutput and
follow storage recovery instead of retrying blindly.
Check RootPath is an absolute path to a directory that exists.
The agent says it cannot find the document
Use a relative name, or an absolute path that still resolves inside RootPath.
io-error on save
Close the file in Word, then check filesystem permissions and the available disk space.
outcome-unknown or registration-failed
Do not repeat the edit. Preserve possibleOutput and follow the recovery procedure to determine whether the output already exists.
Configure broader workflows
The quick start above is deliberately the smallest thing that works. Four settings extend it:
Setting
Adds
OfficeAgent__AllowCreation=true
create_document, so "draft a project brief in brief.docx" makes a new file instead of failing
OfficeAgent__FileSystemConnections__0__AllowedExtensions__0=.docx plus OfficeAgent__FileSystemConnections__0__AllowedExtensions__1=.pptx
Word and PowerPoint on one connection. Declaring this list replaces the .docx default. Set OfficeAgent__FileSystemConnections__0__DefaultChangeMode=Direct for decks, and send "mode": "Tracked" explicitly for reviewable Word edits on that mixed connection.
OfficeAgent__EphemeralConnectionId=session
Names the in-memory session connection explicitly. With no configuration at all the server already falls back to one - this is for running it alongside storage, or under a different id
OfficeAgent__AllowInlineContent=true
Tools that carry the document as base64, for a single self-contained call
Past a couple of settings, use a file instead โ the same OfficeAgent section, where a list
is a list:
Environment variables still override the file. Windows, PowerShell, other MCP clients,
HTTP hosting and SharePoint are in
Deployment and client setup; every setting is listed in
MCP server.
Optional guidance for Word review
skills/word-document-review teaches the review
loop: read comments and pending revisions before editing, keep reviewable Word edits as
redlines, use document ids for multi-step work, and recover from stable error codes. The
installation guide gives complete Bash and PowerShell steps
for Claude Code and Codex, including installation from a fresh machine and verification.
The skill is only needed when the task requires that review discipline; document creation,
ordinary direct edits, and PowerPoint workflows use the server without it.
Optional guidance for application integration
skills/officeagent-integration helps an
implementation agent choose the direct .NET API first, add MCP or Microsoft Agent Framework
only when needed, and run installed-package recipes for tracked editing, template population,
and complete-plan comparison. The installation guide covers both
skills and makes clear that a skill does not install the runtime, NuGet packages, or MCP server.
What reaches the model
The inspect and find tools return document text and structure to the model โ that is how it
locates an edit. Operations on a storage connection keep the package behind an opaque id.
Inline tools carry the whole file as base64 on every call. Session import/export also carries
the package as base64 if the agent performs those calls; a host integration can instead move
the bytes outside model context. Connect storage and model providers appropriate for the data.
The standalone server ships no authentication layer for HTTP hosting; put it behind your own,
or start from the authenticated HostedGateway reference. A
filesystem root is a trust boundary: its ACLs must stop untrusted principals creating,
renaming or replacing entries while the server runs.
After registering services and a document provider, the edit loop looks like
this:
csharp
var client = services.GetRequiredService<OfficeAgentClient>();
var doc = await client.RegisterAsync("workspace", "/srv/workspace/contract.docx");
var inspect = await client.InspectAsync("workspace", doc.ItemId);
var hit = (await client.FindAsync(
"workspace", doc.ItemId, new FindQuery("Acme Corp"))).First();
var plan = new DocumentPlan
{
Snapshot = inspect.Snapshot,
Revision = new RevisionMetadata { Author = "OfficeAgent Quickstart" },
Operations = new PlanOperation[]
{
new ChangeTextOp
{
Target = hit.Anchor,
With = "Globex Inc.",
Mode = ChangeMode.Tracked
}
}
};
var preview = await client.PreviewAsync("workspace", doc.ItemId, plan);
if (preview.IsValid)
await client.CommitAsync("workspace", doc.ItemId, plan);
Revision.Author is the name Word displays for the tracked change. It is not an
authenticated actor identity. See revision identity and audit receipts.
The complete example, including service registration and reading the saved
file, is in Getting started. The minimal direct-.NET
sample runs against the bundled fictional contract, so it needs no MCP client,
language model, or document of your own:
bash
dotnet run --project samples/QuickEdit -- \
samples/documents/services-agreement.docx quickedit-output.docx
Open quickedit-output.docx in Word and verify that the payment term is a tracked
change while the existing revision, comment, table, and headings remain intact.
QuickEdit also accepts an exact source and replacement text
for your own document. Releases also attach quickedit-sample.zip, a package-backed
copy that runs outside the repository against the released NuGet packages.
The repository also contains a
direct IChatClient Word-editing sample and an
interactive
Agent Framework sample, plus a complete
contract-review agent that separates model judgement from
validated document writes. The TemplateBatch sample generates two
quotes from one tagged template, while DocumentComparison
turns covered body-paragraph differences into a reviewable Word redline.
The DocumentAssembly sample combines a proposal, statement of
work, and appendix into one editable package with a multi-source audit receipt. See
Word document assembly for its formatting and compatibility scope.
LiabilityCap changes a value in a commented table cell as a tracked
change, TableRowInsertion adds a table row as a tracked change and
keeps the existing comments, and PageCounter counts rendered pages with
the optional rendering package.
How it works
Every edit follows the same four steps:
Inspect returns a structured map of the document: its outline,
paragraphs, styles, content controls, tables, images, and revisions.
Find searches text and returns a content-verified anchor for each match.
Preview validates a plan against the current document and reports the
proposed changes without writing.
Apply commits the complete plan and saves it through the configured
provider.
A plan (DocumentPlan) is a typed, JSON-serialisable list of operations. An
anchor records both a location and the content expected there. If the content
or optional document snapshot has changed, validation fails instead of silently
targeting a different location. All operations are applied to one in-memory transaction or
none are; a later provider failure can still leave storage uncertain, so callers must inspect
writeOutcome before retrying.
The Word module supports changes to text, paragraphs, tables, images, styles,
content controls, comment threads, footnotes and endnotes, page geometry and
breaks, document properties, and tracked revisions. Operations with a Word revision
representation record a redline when the connection asks for one - an inserted clause,
a deleted row and a restyled heading all come back as revisions a reviewer
accepts or rejects, not only a replaced phrase. Image resizing is applied directly because
WordprocessingML has no revision representation for drawing dimensions. The
PowerPoint module implements a broad, explicitly documented set of deck
operations: text, bullets, run and paragraph formatting, template
slots, style copying, tables, images, text boxes, embedded video and audio,
speaker notes, resolvable comments, footers and slide numbers, sections,
transitions and animations, and the slide lifecycle - adding, removing,
reordering and duplicating. Several slide inserts in one plan author a deck end
to end, so a single call turns nothing into a finished presentation. Any verb it
does not support is named rather than silently skipped. The full operation
schema is documented in Document plans, and the deck
specifics in PowerPoint support.
Documents are accessed through configured providers. After registration,
editing calls use a (connectionId, documentId) pair instead of a storage path
or credentials. The filesystem provider restricts registrations to its root;
the SharePoint, iManage Work, Google Drive and Box providers use the permissions of their
configured identity, and the Azure Blob Storage and Amazon S3 providers keep registrations
under the connection's prefix.
CreateAsync starts a new document inside a connection: the requested .docx,
.pptx or .xlsx extension selects a registered blank-document factory.
CreateFromTemplateAsync starts it as a copy of a template instead, and only reads the
template; a .dotx, .potx or .xltx template becomes a normal .docx, .pptx or .xlsx.
The engine applies an optional initial plan in memory, and then asks
the provider to create and register it without overwriting an existing name.
Publishing to NuGet, PyPI, the MCP Registry, and GitHub
Contributing
Bug reports, documentation fixes, new document operations, provider
integrations, and focused test cases are useful contributions. If you found a problem,
open an issue with the
document feature involved, the operation you attempted, and the error or
unexpected result. Do not attach confidential documents; a small sanitised
reproduction is enough.
To work on the code, install the .NET 10 SDK, fork the repository, and run:
bash
dotnet build OfficeAgent.NET.sln
dotnet test OfficeAgent.NET.sln
Before starting a larger change, especially one that changes public types or
the JSON wire format, open an issue
so the design can be discussed. See
CONTRIBUTING.md
for code style, tests, and pull-request expectations.
Scope and limitations
OfficeAgent.NET edits Word .docx, PowerPoint .pptx, and Excel .xlsx files;
it does not automate the Office desktop applications. It does not decrypt: a file protected by a
sensitivity label or a password is refused with encrypted-document. It does not start a
document from a macro-enabled template or document, which is refused with
macro-enabled-document.
The deck module refuses the verbs a presentation has no vocabulary for -
setProperty, revision, pageSetup, insertBreak and note - per
operation, rather than applying part of a plan, and refuses an explicit tracked
mode on any verb that carries one. PresentationML has no redline model, so tracked changes are Word-only, and
a slide has no header (that is a notes and handout concept). Animations cover
the effects expressible as a filtered p:animEffect; fly-in, zoom and motion
paths are refused rather than approximated. See
PowerPoint support for what a deck does and does not
accept.
The core engine does not render pages, calculate Word fields, or evaluate Excel formulas.
Formula edits set the workbook to recalculate when Excel opens it. The optional
OfficeAgent.Excel.Calculation package calculates a verified set of Excel functions and
writes the results as cached values; see formula calculation. Operations that depend on
pagination, table-of-contents rendering, or field recalculation are outside the core scope.
Preview reports structural changes. The optional rendering package can
produce PDF-derived page images through external processes, but it does not yet detect overflow
or page-fit problems. Test the workflow on representative documents and keep human review in the
loop for consequential edits.
Two more limits worth knowing before you build on it:
Token savings depend on how you connect. Addressing a document by id keeps
the package out of the conversation, and inspection can be narrowed with
fidelity and paging - that is where the saving comes from. The inline
*_content tools are the deliberate exception: they carry the whole file as
base64 in both directions, which costs tokens in proportion to file size. They
suit a single self-contained call, not a sequence of edits - a model asked to
pass a document of a few kilobytes back for a second edit reproduces it
imperfectly and the follow-up fails. Use a connection, or a session connection,
when more than one edit is coming.
Review guidance is optional. For review tasks, the server alone does not make an
agent read open comments before editing or choose a redline. The
word-document-review skill teaches that workflow;
without it, review behaviour depends on the model and the prompt.
Commercial support
OfficeAgent.NET is MIT-licensed and can be self-hosted. Commercial support and
deployment assistance are available from dotaction:
contact dotaction.
That service is separate from the project: it is governed by its own agreement and does not change
the library's license, compatibility promise or community support policy.
Privacy Policy
OfficeAgent.NET runs on your machine or your own server and collects nothing: no telemetry, no
analytics, no calls home. It reads and writes only the documents in the folders, SharePoint
libraries, other document stores, or session connections it is given, and contacts no third
party except the storage service of a connection a host configures: SharePoint, iManage Work,
Google Drive, Box, Azure Blob Storage or Amazon S3. Tool results go to the AI assistant using
it, under that assistant's own policy. The full policy, including what is stored and for how
long, is in PRIVACY.md.
Connection id the agent uses to address documents on the filesystem (any non-empty string). Optional: with nothing configured the server starts with an in-memory session connection whose documents last only while it runs. Set this and RootPath to edit documents on disk instead; SharePoint is OfficeAgent__SharePointConnections__0__*
OfficeAgent__FileSystemConnections__0__RootPath
Absolute path to the directory this filesystem connection may read and write documents under. Only .docx is allowed unless OfficeAgent__FileSystemConnections__0__AllowedExtensions__N adds more (.pptx for decks or .xlsx for workbooks). Deck connections usually want OfficeAgent__FileSystemConnections__0__DefaultChangeMode=Direct because PowerPoint cannot record tracked changes
OfficeAgent__AllowCreationdefault false
Set to true to expose create_document, so an agent can author a new file in the connection rather than only editing existing ones. Off by default: creating agent-named files under a connection root is a capability the host should choose deliberately