WordCraft MCP Setup: Connect a Local Document Editor to Claude

WordCraft includes a local MCP server that lets compatible AI clients work with documents through its command-line tools. The browser editor on this site does not install or run that server. For MCP, you need the upstream WordCraft CLI on your computer and an AI client that can launch a local MCP process.

This guide follows the upstream v0.5.0 MCP documentation, reviewed October 12, 2026. It is a documented setup recipe, not a claim that we independently completed an end-to-end Claude session. Client settings and available tools can change between releases.

Prepare the local tools

Use the download guide to reach the official releases. The desktop application and the command-line executable have different roles: installing a graphical editor does not establish that wordcraft-cli is available in your terminal.

Check that both the WordCraft CLI and your chosen AI client are installed. For the Claude Code example below, claude must also be an available command. If your system reports “command not found,” locate the executable before continuing; repeating the MCP registration will not install it.

Choose a dedicated folder with a disposable document, such as mcp-test.docx. Decide in advance that the output should be a new file, mcp-test-edited.docx. This makes the agent's intended action and its result easy to review.

Option 1: headless document editing

The upstream command for registering a headless server with Claude Code is:

claude mcp add wordcraft -- wordcraft-cli mcp

Headless means that document operations happen without opening a WordCraft window. You can name the agent's revision author by configuring the server command with --author, as documented upstream:

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

That second command starts a server process; it is not another registration command. A process waiting for MCP messages may appear idle in a terminal. Let the AI client launch the configured server rather than expecting an interactive editing prompt from it.

Option 2: control a running desktop window

Start the WordCraft desktop application with a local control port:

wordcraft --control 7981

Keep that application running. In a separate terminal, register the bridge:

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

Use this mode when the task requires the running application's interface. The control protocol describes a per-window key and a loopback connection. The bridge reads that key from the application's local key file or the documented environment variable. This is separate from the browser edition and from a remotely hosted AI service.

Verify one small edit

Ask the agent for a tightly scoped task:

Open mcp-test.docx. Read the document and report its headings. Change only the sentence “Draft for review” to “Ready for review.” Save a new file named mcp-test-edited.docx, then read it back and report what changed.

The important part is the sequence: inspect, make a limited change, save, inspect again. A message saying “done” is not evidence that the correct file was saved. Open the output yourself and compare the changed sentence, surrounding text, and page layout.

For reviewable changes, upstream documents an explicit review.trackChanges command with value: true. An explicit value avoids accidentally toggling tracking off when it was already enabled. Ask the agent to discover the available commands before relying on a remembered command name.

If the connection does not work

| Symptom | First check | | -------------------------------------- | ---------------------------------------------------------------------------- | | Executable not found | Can the same terminal locate wordcraft-cli and the AI client? | | Desktop connection refused | Is the app running with the same port used by the bridge? | | Unauthorized control request | Is the bridge reading the key for the current application instance? | | Tools appear but the document is wrong | Check the file path and inspect the document before editing | | Output is missing | Check the requested save path and ask the agent to read that exact file back |

Document content exposed to an AI client may be processed by that client's provider under its settings and policies. The fact that WordCraft runs locally does not describe what an independently connected AI service does with text.

For the manual workflow, see WordCraft getting started. For current tool names and configuration changes, use the official repository documentation.