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

Tool	What it does
pureref_list_scenes	Lists the .pur boards in a folder
pureref_scene_info	Shows where each image on a board came from (local file or web URL) without launching PureRef
pureref_view_scene	Renders the board with a scene-coordinate grid, optionally zoomed to a region
pureref_view_images	Shows a numbered contact sheet of the board's images
pureref_export_images	Exports full-resolution copies of the images
pureref_render_png	Renders the board to a PNG
pureref_add_items	Places images (paths or URLs) and text labels at exact positions
pureref_add_image_grid	Places a grid of images
pureref_build_board	Lays out a titled board from sections of images in one go
pureref_open	Opens a board in the PureRef app
pureref_list_backups	Lists the automatic backups of a board

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.

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)

Variable	Default	What it's for
PUREREF_MCP_ROOT	~/Documents/PureRef	The folder that relative board names and pureref_list_scenes use
PUREREF_EXE	Looks in Program Files	Path to PureRef.exe, if it's installed somewhere else
PUREREF_MCP_CACHE	%LOCALAPPDATA%\pureref-mcp	Where previews, downloads and backups go

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.