pureref-mcp

An MCP server that lets an AI assistant (Claude Code, Claude Desktop or any MCP client) work with PureRef 2.x on Windows. It can build reference boards from folders, export them, and drive a live PureRef window: every menu action, the mouse, notes, pasting files and dialogs.

PureRef has no API. Its command line has six commands (load, clearScene, save, exportScene, exportImages, exit), and the .pur format is closed. This server combines two channels to get the rest.

Unofficial project, not affiliated with PureRef / Idyllic Pixel. Tested with PureRef 2.1.3 on Windows 10.

Install

Requires Windows, Python 3.11+ and PureRef 2.x.

git clone https://github.com/Flamtiwork/pureref-mcp
cd pureref-mcp
uv venv .venv
uv pip install --python .venv\Scripts\python.exe -e .

Register it with Claude Code:

claude mcp add pureref -s user -- "C:\path\to\pureref-mcp\.venv\Scripts\pureref-mcp.exe"

Or in any MCP client config:

{
  "mcpServers": {
    "pureref": {
      "command": "C:\\path\\to\\pureref-mcp\\.venv\\Scripts\\pureref-mcp.exe",
      "env": { "PUREREF_EXE": "C:\\Program Files\\PureRef\\PureRef.exe" }
    }
  }
}

PUREREF_EXE is optional. It defaults to C:\Program Files\PureRef\PureRef.exe.

Related MCP server: com-use-mcp

1. Headless boards (CLI)

These tools run a separate, minimized PureRef process that runs the commands and exits. No focus is stolen.

PureRef quirks handled for you:

• after load;<file.pur> PureRef can only save back to the same path, so "save as" copies the file first;

• long command lists are split across several runs (the Windows command line has a length limit);

• headless runs restore PureRef's Recent files list afterwards.

2. Live window

The server gives every PureRef action (93 of them: the whole context menu and the Keyboard shortcuts page) an extra alias shortcut on F13–F24 with modifiers. No physical keyboard has these keys, so the aliases never clash with your own shortcuts.

The aliases are written to %APPDATA%\PureRef\PureRef.ini, section [Key_Bindings], as <Action_Id>1Shortcut=Ctrl+F13:

• a backup of the original file is kept as PureRef.ini.pureref_mcp.bak;

• they show up in PureRef's settings as extra aliases;

• PureRef reads the ini only at startup, so restart any window that was open before setup_bindings.

To run an action, the server brings PureRef to the front, presses the alias and gives focus back to the window you were in.

PureRef's own dialogs (Export images, unsaved changes) are Qt windows with no accessibility. After each call the server lists them in the dialogs field, and the assistant handles them from a screenshot with live_mouse and live_type.

What did not work, and why the design looks like this:

• the Command Palette (Ctrl+Shift+P) closes without running the command on synthetic input, so aliases are used instead;

• a "System global" binding (Context=4) does not fire these actions while PureRef is unfocused, so the window is focused for each action.

Notes

• Windows only: it uses pywinauto, pywin32 and the Windows clipboard.

• Live tools move the mouse and focus for a moment. Don't type into other apps while an assistant is driving PureRef.

• Action ids were checked against PureRef 2.1.3. Other versions may rename some actions: if an action has no effect, look for its alias in PureRef's Settings → Keyboard shortcuts.

License

MIT