PureRef MCP

An MCP server that lets an AI agent (Claude Code, Claude Desktop, or any MCP client) see and build PureRef reference boards.

It drives PureRef 2.1+'s official command-line interface. Each call runs PureRef as a separate headless process, so an open PureRef window is never touched.

What it can do

How it stays safe

• Backups: before a board is written, the original is backed up. The last 20 backups per board are kept in %LOCALAPPDATA%\pureref-mcp\backups.

• Open boards: writing a board that's open in the PureRef window is refused unless allow_open=true.

• Atomic saves: saves go to a temp file first, then replace the original.

Limits (from PureRef's CLI)

• It can't move, resize, delete or relabel items that are already on a board. It can only add new ones.

• Text labels are added as images, not native PureRef notes.

• Reopen the board in PureRef to see the changes.

Related MCP server: gimp-agent-mcp

Requirements

• Windows. The CLI and exe lookup are only tested there.

• PureRef 2.1 or newer.

• Python 3.11+.

Setup

1. Install the Python packages:

   pip install -r requirements.txt

2. Register the server with your MCP client. For Claude Code:

   claude mcp add pureref -s user -e PUREREF_MCP_ROOT="C:\path\to\your\boards" -- python "C:\path\to\PureRef-MCP\server.py"

   For Claude Desktop, or any client that uses an mcpServers JSON config:

   {
     "mcpServers": {
       "pureref": {
         "command": "python",
         "args": ["C:\\path\\to\\PureRef-MCP\\server.py"],
         "env": { "PUREREF_MCP_ROOT": "C:\\path\\to\\your\\boards" }
       }
     }
   }

Settings (environment variables)

Coordinates

• Positions are in PureRef scene units: 1 unit is 1 image pixel at 100% zoom.

• x grows to the right and y grows downward.

• Image positions are centers unless you pass anchor="top_left".

• pureref_view_scene draws the grid (cyan x= lines, yellow y= lines), so the agent can read positions off the preview.

License

MIT, see LICENSE. PureRef is a product of Idyllic Pixel AB. This project isn't affiliated with or endorsed by them.