Install
& connect

Get the minipainter CLI, then hand your bench to any MCP-capable agent. Every path below, start to finish. Node 18 or newer, that is the only prerequisite.

1 · Get the CLI

Run it straight from npm with npx, no clone, no setup. The 1,607 paint catalog is bundled, so search and matching work on the first run.

# run straight from npm
$ npx minipainter paint search bone
$ npx minipainter match color "#d2c29b"
$ npx minipainter tui

Or install it globally to get the short mpaint command everywhere:

# install once, call from anywhere
$ npm install -g minipainter
$ mpaint paint search bone

Prefer to work from source? Clone and run against the working tree:

# hack on it locally
$ git clone https://github.com/arturskowronski/minipainter
$ cd minipainter && npm install
$ node src/cli.mjs paint search bone

Your inventory lives at ~/.minipainting/inventory.json, created automatically the first time you mark a paint owned. A legacy ~/.warpaint/ is migrated on first run.

2 · Connect an agent

minipainter speaks the Model Context Protocol, so it plugs into any agent that does. Pick the one you use.

Claude Desktop · local

Local MCP server

Add minipainter to claude_desktop_config.json, then restart Claude Desktop. It reads and updates your local inventory directly.

// claude_desktop_config.json
{
  "mcpServers": {
    "minipainter": {
      "command": "npx",
      "args": ["-y", "-p", "minipainter", "minipainter-mcp"]
    }
  }
}

From a clone, use "command": "node" with the absolute path to src/mcp-server.mjs.

Claude web · ChatGPT · Gemini

Self-hosted remote MCP

For URL-based agents, deploy your own remote MCP (step 3 below), then add your URL as a custom connector in the client's settings. Claude web and Gemini use /mcp; ChatGPT uses the search / fetch route at /mcp/v3.

https://your-app.fly.dev/mcp

https://your-app.fly.dev/mcp/v3

Your server, your inventory. There is no public instance to share.

Claude Code · skill

Agent Skill

Fetch the skill straight from this site, no clone required. It ships with the right guardrails baked in: JSON-only reads, product_format rules, failure handling.

# project-scoped
$ mkdir -p .claude/skills/minipainter
$ curl -fsSL https://arturskowronski.github.io/minipainter/SKILL.md \
     -o .claude/skills/minipainter/SKILL.md

Or save it to ~/.claude/skills/minipainter/SKILL.md to use it everywhere.

3 · Self-host the hosted endpoint

Want your own remote MCP with a private inventory rather than the shared one? Two paths, pick one.

Local · Docker + Postgres

Run it on your machine

Bring up the server and Postgres together with one command.

# from the repo
$ docker compose up -d
$ curl localhost:3000/health

Set DATABASE_URL to move inventory into Postgres; without it, inventory stays in a JSON file.

Cloud · Fly.io

Deploy your own instance

A single-user remote MCP with a persistent volume, reachable from anywhere.

# claim the app name, no deploy yet
$ fly launch --no-deploy --copy-config --name your-app-name
# volume for inventory.json (skip if you attach Postgres instead)
$ fly volumes create inventory_data --region <region> --size 1
# bearer token for the /inventory sync endpoint
$ fly secrets set INVENTORY_SYNC_TOKEN="$(openssl rand -hex 32)"
$ fly deploy

Full walkthrough (Postgres mode, ChatGPT connector, smoke tests) in docs/deploy-fly.md in the repo.

Install& connect