Minipainter
@ArturSkowronski
About Minipainter
Local-first miniature-paint inventory and cross-brand color matching for AI agents. Search 1,607 paints across Citadel, Army Painter, Vallejo, and AK Interactive; match a hex color or a description to the nearest paint; and track which paints you own so an agent recommends what's
Config
Add this server to your MCP-compatible client using the configuration below.
{
"mcpServers": {
"minipainter": {
"command": "npx",
"args": [
"-y",
"-p",
"minipainter",
"minipainter-mcp"
]
}
}
}Tools
7Search paints by name, alias, provider, owned state, role, or color family.
Show one paint or return ambiguous/not_found resolution results.
List owned paints from the local inventory.
Mark a paint as owned in the local inventory.
Mark a paint as not owned in the local inventory.
Match paints by approximate color with owned-first ranking.
Match paints from a semantic description like bone or silver metallic.
Overview
What is Minipainter?
Minipainter is a local-first paint registry for miniature-painting workflows. It maintains a deterministic catalog of 1,607 paints (Citadel, Army Painter, Vallejo, AK) and a personal inventory of owned paints, enabling AI paint suggestions that understand what you actually have. It provides a colored terminal UI (TUI), CLI, and MCP servers for both Claude Desktop and ChatGPT.
How to use Minipainter?
Install with npx minipainter or globally via npm install -g minipainter. Run CLI commands like paint search, match color, or tui to interact with the catalog and inventory. For Claude Desktop, add an MCP server entry in its configuration pointing to src/mcp-server.mjs. For self‑hosted Docker, use docker compose up --build (includes Postgres) or build the image and run with a volume. The HTTP server exposes REST endpoints and an MCP transport.
Key features of Minipainter
- Owned-first matching for paint lookup and recommendations
- Local catalog (bundled) and personal inventory (JSON or Postgres)
- RGB‑aware search and cross‑brand color matching
- Colored TUI with per‑paint RGB swatches and ownership status
- Agent‑friendly CLI and MCP servers for Claude Desktop and ChatGPT
- Deterministic, version‑controlled paint IDs
Use cases of Minipainter
- Miniature painters who want AI paint suggestions based on their actual collection
- Tracking which paints you own across multiple brands
- Finding closest color matches from owned paints for a target color or description
- Integrating paint inventory into Claude Desktop workflows (search, ownership updates)
FAQ from Minipainter
What paints are included in the catalog?
The catalog covers 1,607 paints across Citadel, Army Painter, Vallejo, and AK. It is bundled and kept in version control at data/catalog/.
How is my inventory stored?
By default, inventory is stored locally at ~/.minipainting/inventory.json. In Docker (with Postgres) it persists in a named volume that survives container restarts and docker compose down; only down -v wipes it.
Can I use Minipainter without a database?
Yes. When DATABASE_URL is unset, Minipainter uses a local JSON inventory file. Alternatively, you can run the Docker stack with Postgres for persistence.
What transports/auth does the MCP server support?
The MCP server supports stdio (for Claude Desktop) and Streamable HTTP (for Claude mobile/web) via mcp-http-server.mjs. The HTTP endpoints can be protected with an AUTH_TOKEN for /api/* and /mcp, and an INVENTORY_SYNC_TOKEN for the sync endpoint.
Known limits: how accurate are the RGB values?
RGB values in the catalog are approximate reference colors for matching, not a guarantee of final painted appearance.
Frequently asked questions
What paints are included in the catalog?
The catalog covers 1,607 paints across Citadel, Army Painter, Vallejo, and AK. It is bundled and kept in version control at `data/catalog/`.
How is my inventory stored?
By default, inventory is stored locally at `~/.minipainting/inventory.json`. In Docker (with Postgres) it persists in a named volume that survives container restarts and `docker compose down`; only `down -v` wipes it.
Can I use Minipainter without a database?
Yes. When `DATABASE_URL` is unset, Minipainter uses a local JSON inventory file. Alternatively, you can run the Docker stack with Postgres for persistence.
What transports/auth does the MCP server support?
The MCP server supports stdio (for Claude Desktop) and Streamable HTTP (for Claude mobile/web) via `mcp-http-server.mjs`. The HTTP endpoints can be protected with an `AUTH_TOKEN` for `/api/*` and `/mcp`, and an `INVENTORY_SYNC_TOKEN` for the sync endpoint.
Known limits: how accurate are the RGB values?
RGB values in the catalog are approximate reference colors for matching, not a guarantee of final painted appearance.
Basic information
More MCP servers
Vibgrate MCP
VibgrateQuery your team's drift, vulnerability, and migration data from any AI assistant. Vibgrate MCP connects Cursor, Claude, ChatGPT, Windsurf, or VS Code to Vibgrate Cloud: 51 tools for DriftScores, CVEs and EOL runtimes, up
fhirHydrant
faulkjOpen-source Node.js FHIR MCP server with SMART Backend Services, metadata-aware search/CRUD tools, compact responses, FHIRPath filtering, safe pagination, audit events, and terminology lookup.
ctxfile
ctxfileLocal-first MCP server that snapshots your project's working state into one context object. Open-core, privacy-first.
scvd.store
seancrecordThe trust layer of the x402 economy. Free conformance checking for any issuer's x402 signed offers and receipts. Settlement attestation on Base and Solana. Weekly signed, Bitcoin-anchored ecosystem corpus.
q-ring
I4cTimeQuantum-inspired keyring for AI coding agents. Secure secrets with superposition, entanglement, tunneling, and teleportation — CLI + 44 MCP tools.
Comments