WordCraft MCP server and command line

WordCraft comes with a command-line tool, wordcraft-cli. It converts and inspects documents without opening a window, and it runs an MCP (Model Context Protocol) server, so AI agents such as Claude can create, edit and save documents. Every action in WordCraft is a command with an id. According to the README, the same 422 commands drive the ribbon, the keyboard shortcuts, the command line and the MCP server.

This page summarises the official documentation at version 0.7.0. We haven’t tried these setups ourselves, so check the MCP docs if something doesn’t match.

Where to find wordcraft-cli

The examples below write wordcraft-cli. Replace it with the full path if it isn’t on your PATH.

Convert and inspect documents

These commands come from the README:

# Convert to PDF, or to odt, rtf, html, md, tex, txt or png
wordcraft-cli convert report.docx report.pdf
# Print the text only
wordcraft-cli text report.docx
# Print the document's structure as JSON
wordcraft-cli inspect report.docx

run applies commands to a document and saves the result. This example starts from the built-in sample, selects the word “Membership”, makes it bold and saves a new file:

wordcraft-cli run --template sample \
  --cmd 'select.text={"text":"Membership"}' --cmd format.bold --save out.docx

In Windows PowerShell, put & and the quoted path in front:

& "C:\Program Files\WordCraft\wordcraft-cli.exe" convert report.docx report.pdf

Connect an AI agent over MCP

The server talks to the agent over standard input and output, and works in one of two ways:

• Without a window (wordcraft-cli mcp). The agent creates, opens, edits and saves documents in the background. This is the mode you can confine to certain folders.
• Driving the running app (wordcraft-cli mcp --connect). You watch the agent work in WordCraft’s window, and it can also take screenshots, click and press keys.

For Claude Code, the README gives this command:

claude mcp add wordcraft -- wordcraft-cli mcp

Other MCP clients take a JSON entry like the one below. The docs use this shape. Use the full path to wordcraft-cli, and look up where your client keeps its MCP settings in its own documentation.

{
  "mcpServers": {
    "wordcraft": {
      "command": "/full/path/to/wordcraft-cli",
      "args": ["mcp"]
    }
  }
}

To drive the app instead, start WordCraft with a control port, then connect the server to it:

wordcraft --control 7981 &
claude mcp add wordcraft-app -- wordcraft-cli mcp --connect 127.0.0.1:7981

On a Mac, start the app with open -a WordCraft --args --control 7981. On Windows, open PowerShell in its folder and run & .\wordcraft.exe --control 7981.

What the agent can do

Keep the agent to certain folders

Start the server with a read folder and a write folder:

wordcraft-cli mcp --automation-read-root /work/project --automation-write-root /work/project/out

{
  "mcpServers": {
    "wordcraft": {
      "command": "/full/path/to/wordcraft-cli",
      "args": ["mcp", "--automation-read-root", "/work/project", "--automation-write-root", "/work/project/out"]
    }
  }
}

According to the docs:

• Every file the agent opens or reads must be inside the read folder: documents, templates, pictures, mail-merge lists and documents to compare. Every file it saves or exports must be inside the write folder.
• Read and write access are separate. If you give only a read folder, nothing can be written to disk. To allow both in one place, give the same folder twice.
• Links that lead out of a folder count as outside it, and /work2 doesn’t count as inside /work. A refused path comes back to the agent as an ordinary error it can read and correct.
• Both folders must already exist, or the server stops with an error.
• The limits apply only to the server without a window. They can’t be combined with --connect, and the desktop app has no such limits yet, so an app started with --control isn’t confined.
• They don’t limit what the agent does to the document already open. It can still read all of it and change it.

The docs also say what the folders don’t protect against: a path is checked and then opened, so another program that swaps a link in between could still win. The folders keep an agent to the files you gave it. They don’t guard against other software on your computer.

Mark the agent’s edits

Tracked changes and comments are recorded under the session’s user name, “WordCraft User” by default. To tell the agent’s edits from people’s, give it a name when you start the server:

wordcraft-cli mcp --author "Claude (copyedit)"

Have the agent turn tracking on with review.trackChanges {"value": true}. Without value, the command switches tracking the other way, which turns it off in a document that was saved with tracking on.

How driving the app is protected

The control port is off unless you start WordCraft with --control. It listens only on your own computer (127.0.0.1). Because any local program, and possibly a web page, can reach such a port, every request also needs the window’s key: 256 random bits that the app writes to a file in its settings folder and removes when the window closes. A wrong or missing key gets the connection closed.

wordcraft-cli mcp --connect reads that key itself, and sends it only to addresses on your own computer. To drive WordCraft on another machine, the docs suggest forwarding its port over SSH (ssh -L 7981:127.0.0.1:7981 host) and setting WORDCRAFT_CONTROL_KEY to that app’s key.

Before you rely on it

• Your AI service sees the text. WordCraft itself works offline, but whatever the agent reads, it sends to the AI service behind it. Don’t hand it documents you wouldn’t share with that service.
• Check the result. The docs warn that a property name WordCraft doesn’t recognise is ignored rather than refused, so a typo fails without an error. Have the agent read the document back with inspect_document.
• Alpha limits apply. Documents an agent writes have the same limits as any WordCraft document: page breaks can differ from Word, and real-world .docx files haven’t been tested systematically. The Word comparison lists the main gaps.
• Keep copies. Let the agent work on copies, or in a separate write folder, until you trust the setup.

Sources

docs/mcp.md, docs/control-protocol.md and the README at version 0.7.0. The file locations come from the 0.7.0 packaging files: the Windows installer definition, the Linux packaging script and the Flatpak manifest.