Minipainter

MCP开发工具

提供方 ArturSkowronski

开发工具 未标注 API Key 社区 / 第三方 Claude DesktopClaudeCursorCodex

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

一句话选型结论

按资料字段整理

Minipainter 属于开发工具类 MCP 服务器,传输方式未标注,API Key,可直接接入 Claude Desktop、Claude、Cursor 等,没有现成安装命令,需按官方文档接入。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类开发工具 传输方式未标注 鉴权API Key 部署方式未标注
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

开发工具
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

clilocal first

安装与配置

未标注 API Key
上游未给出传输方式
  1. 1
    准备运行环境

    按官方文档确认运行环境(常见为 Node.js 或 Python),装好后再执行安装命令。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
代码与仓库操作

在对话里直接查代码、提 issue、走 PR,省掉来回切工具。

本地命令与脚本

把构建、测试、格式化这类重复命令交给模型执行。

接口联调与测试

让模型调你的接口、跑一遍用例,快速定位问题。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • 没有现成安装命令,需要按官方文档自己填启动命令和参数。
  • 使用前要准备好API Key对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在开发工具场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Minipainter当前 未标注 未标注 未标注 无 未标注
Git 838e2ec1 12 stdio · 本地进程 本地部署 有 2026-05-17
Markitdown MCP 2c653a5f 1 stdio · 本地进程 本地部署 有 2026-05-17
JavaGuide 未标注 stdio · 本地进程 本地部署 有 2026-04-11
awesome-claude-skills 未标注 stdio · 本地进程 本地部署 有 2026-04-26
Context7 831acf40 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

开发工具
字段来自项目仓库与公开索引,中文说明由本站标注
提供方ArturSkowronski上游标注的维护方 ArturSkowronski
分类开发工具本站按上游分类展示
连接方式未标注上游未给出传输方式
鉴权方式API Key远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · node本地安装时用到的包标识与运行时
部署类型未标注上游给出的部署形态
最近核验未标注上游最后核验时间

详细介绍

13.4 KB
来自项目仓库与上游目录的原文,未做删改

MINIPAINTER

> The paint bench, indexed.

Site: arturskowronski.github.io/minipainter

minipainter is a local-first paint registry for miniature-painting workflows. It exists for one practical reason: AI paint suggestions are much more useful when they understand the paints you actually own.

The project gives you:

  • a deterministic local catalog (1,607 paints across Citadel, Army Painter, Vallejo, AK) and inventory
  • owned-first paint lookup and cross-brand color matching
  • a colored terminal UI (TUI) that shows each paint's real RGB as a swatch
  • MCP servers for both Claude Desktop and ChatGPT
  • a CLI surface designed for both humans and agent workflows

The colored TUI

The ledger TUI is a real colored terminal app: a MINIPAINTER banner, gold section
frames, green OWNED / red MISSING status, and a truecolor swatch of every paint's own
RGB. Color turns on for a TTY and honors NO_COLOR.

Why This Exists

Most paint advice workflows break at the same point: they recommend paints you do not have on hand.

minipainter is built to solve that exact problem:

  • keep a local record of what is in your paint rack
  • search it quickly by name, role, family, and approximate color
  • prepare a stable inventory foundation for a future AI skill that can inspect links, photos, and model images

The long-term goal is not “AI picks random colors for miniatures.” The goal is “AI reasons from your actual inventory first, then suggests stronger alternatives only when useful.”

Feature Highlights

  • Owned-first matching: lookups and recommendations can prioritize paints you already have.
  • Catalog in repo, inventory in your home: paint records live in data/catalog/; what you own lives in ~/.minipainting/inventory.json and follows you across projects.
  • RGB-aware search: approximate RGB values help with nearest-color matching.
  • Colored TUI: terminal ledger with per-paint RGB swatches and OWNED/MISSING status.
  • Agent-friendly CLI: deterministic command output for AI integration (Claude + ChatGPT MCP).

Screenshots

Hero Screen

Full-screen TUI with banner, catalog, detail panel, and command strip.```text
See: docs/assets/hero.txt


### Search View

Filtered lookup for a semantic search like `bone`.```text
See: docs/assets/search.txt

Owned View

Inventory-only presentation focused on what is already bound to your collection.```text
See: docs/assets/owned.txt


### CLI Flow

Representative command-line usage for search, ownership updates, and color matching.```text
See: docs/assets/cli.txt

Run with Docker (Postgres)

The whole stack — MCP/HTTP server plus a Postgres that stores your inventory — starts with
one command. Inventory persists in a named volume, so it survives container restarts and
docker compose down / recreation
(only down -v wipes it).```bash
docker compose up --build # http://localhost:3000


- `GET /health` — liveness
- `GET /api/inventory` — owned paints (from Postgres)
- `POST /mcp` — MCP for Claude Desktop · `POST /mcp/v3` — MCP for ChatGPT (`search`/`fetch`)

Storage is selected by `DATABASE_URL`: set it (as `docker-compose.yml` does) for Postgres,
leave it unset to use a local JSON inventory file (unchanged local behavior). See `.env.example`.

## Deploy

Any Docker + Postgres host works (Fly.io, Railway, a VPS…). For a one-click remote MCP
server with a managed database, the repo ships a **Render Blueprint** (`render.yaml`) that
provisions the web service and Postgres together and wires `DATABASE_URL` automatically:

The reference deployment `warpaint-mcp.fly.dev` runs on Fly.io with Fly Managed Postgres — see
`docs/deploy-fly.md` for the `fly mpg attach` + migration steps.

## Install

The fastest way — run it straight from npm with `npx`, no clone, no install:```bash
npx minipainter paint search bone
npx minipainter match color "#d2c29b"
npx minipainter tui

Or install it globally to get the short mpaint command everywhere:```bash
npm install -g minipainter
mpaint paint search bone
mpaint match color "#d2c29b"


The catalog is bundled, so search and matching work on first run with nothing to configure. Your inventory lives at `~/.minipainting/inventory.json`, created automatically the first time you mark a paint owned (legacy `~/.warpaint/` is auto-migrated).

Requirements:

- Node.js 18 or newer
- POSIX-ish shell (Linux, macOS, WSL)

### From source

To hack on it, clone and run against the working tree:```bash
git clone https://github.com/ArturSkowronski/minipainter.git
cd minipainter
npm install
node src/cli.mjs paint search bone

After that you have four usage modes:

  • CLI / TUI — see Quickstart below
  • Self-hosted HTTP server — a single Docker-friendly runtime with JSON storage and API endpoints
  • Local MCP for Claude Desktop — see Claude Desktop MCP Setup
  • Remote MCP for Claude mobile/web — see Remote MCP

Quickstart

Initialize the local inventory at ~/.minipainting/inventory.json:```bash
node src/cli.mjs catalog sync


Search paints:```bash
node src/cli.mjs paint search black
node src/cli.mjs paint search bone --json

Inspect one paint:```bash
node src/cli.mjs paint show "Abaddon Black" --json


Mark paints as owned or missing:```bash
node src/cli.mjs inventory own "Abaddon Black"
node src/cli.mjs inventory unown "Abaddon Black"
node src/cli.mjs inventory list

Run semantic or color matching:```bash
node src/cli.mjs match describe bone
node src/cli.mjs match color "#d2c29b"


Launch the TUI:```bash
node src/cli.mjs tui

Run the MCP server locally:```bash
node src/mcp-server.mjs


Run the self-hosted HTTP server locally:```bash
DATA_DIR=.minipainting-data node src/mcp-http-server.mjs

TUI Workflow

The TUI is centered around three presentation areas:

  • FORGE CATALOG: visible paints in the current scope
  • SELECTED PIGMENT: the currently highlighted paint with provider, families, usage, and RGB
  • RITUAL COMMANDS: the command legend for the active session

Current TUI commands:

  • search
  • owned
  • catalog
  • toggle
  • quit

Recommended use:

  1. start with catalog
  2. narrow with search bone, search black, or similar queries
  3. inspect the selected pigment panel
  4. toggle ownership as your collection changes

Project Direction

Implemented now:

  • local JSON registry
  • starter provider catalogs for Citadel and Army Painter
  • owned / missing inventory tracking
  • deterministic search and color matching
  • colored terminal presentation with per-paint swatches
  • local MCP server for Claude Desktop

Planned later:

  • a separate skill for parsing paint-set links
  • image-driven inventory fill from paint bottle photos
  • model-photo analysis that recommends owned paints first
  • stronger cross-provider equivalents and matching hints

Technical Notes

  • Built-in catalog data lives in data/catalog/ (Citadel and Army Painter, kept in version control)
  • Inventory file: ~/.minipainting/inventory.json — stores only owned paint ids in the form { "version": 1, "owned": ["citadel/abaddon-black", ...] }
  • Self-hosted server data directory: DATA_DIR (defaults to /data in Docker); inventory lives at /inventory.json
  • The catalog and inventory are composed at runtime; saving never rewrites the catalog
  • IDs are stable by convention (provider + name slug); on load, owned ids missing from the catalog are reported as warnings instead of being silently dropped
  • A pre-existing project-local .minipainting/registry.json next to the inventory path is auto-migrated on first run
  • Legacy .warpaint/ data directories are auto-renamed to .minipainting/ on first run (both home and project-local variants)
  • Override the inventory location at the API surface with { inventoryPath } or { cwd } (the latter resolves to /.minipainting/inventory.json, which is what the test suite uses for isolation)
  • RGB values are approximate reference colors for matching, not a guarantee of final painted appearance
  • MCP entrypoint: node src/mcp-server.mjs
  • MCP helper script: npm run mcp
  • HTTP server helper script: npm run server
  • README demo captures are reproducible via:```bash
    npm run generate:demo

## Claude Desktop MCP Setup

`minipainter` now includes a local MCP server so Claude Desktop can use your paint registry directly.

Example local MCP config:```json
{
  "mcpServers": {
    "minipainter": {
      "command": "node",
      "args": ["/absolute/path/to/minipainter/src/mcp-server.mjs"]
    }
  }
}

After adding the server, Claude Desktop can call tools such as:

  • paint_search
  • paint_show
  • inventory_list
  • inventory_mark_owned
  • inventory_mark_unowned
  • match_color
  • match_describe

Suggested local flow:

  1. initialize your registry once with node src/cli.mjs catalog sync
  2. add the MCP server to Claude Desktop
  3. ask Claude to search paints or update ownership through the exposed tools

Agent Skill

For Claude Code, fetch the skill straight from the site, no clone required. It ships with the
right guardrails baked in: JSON-only reads, product_format rules, failure handling.```bash

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.

## Self-Hosted Docker

The Docker image runs a single HTTP server runtime designed for self-hosted use. Build it from
the repo (no image is published to a registry yet):```bash
docker build -t minipainter .
docker run -p 3000:3000 -v minipainting-data:/data minipainter

Or bring up the server together with Postgres in one step with docker compose up -d.

The server exposes:

  • GET /health
  • GET /api/paints
  • GET /api/paints/:paint
  • GET /api/inventory
  • PUT /api/inventory/:paint
  • DELETE /api/inventory/:paint
  • POST /api/match/color
  • POST /api/match/describe
  • POST /mcp

Optional runtime configuration:

  • PORT — listen port, defaults to 3000
  • DATA_DIR — persistent state directory, defaults to /data in Docker
  • AUTH_TOKEN — protects /api/* and /mcp with Authorization: Bearer ...
  • INVENTORY_SYNC_TOKEN — protects the legacy /inventory sync endpoint

Remote MCP (Claude Mobile)

For Claude mobile or web, the stdio MCP server above is not reachable. Run
minipainter-mcp-http instead — a Streamable HTTP MCP transport exposing the
same tools, plus GET/POST /inventory for syncing the local inventory.

Local smoke test```bash

export INVENTORY_SYNC_TOKEN=$(openssl rand -hex 32)
export PORT=3000
export INVENTORY_PATH=$HOME/.minipainting/inventory.json
npm run mcp:http


Then in another shell:```bash
curl -s http://localhost:3000/health
curl -s -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Sync endpoint (bearer-token protected)
curl -s -H "Authorization: Bearer $INVENTORY_SYNC_TOKEN" \
     http://localhost:3000/inventory

Deploy to Fly.io

The repo ships a Dockerfile and fly.toml. Full recipe in
docs/deploy-fly.md. Short version:bash fly launch --no-deploy --copy-config --name <your-app-name> fly volumes create inventory_data --region <your-region> --size 1 fly secrets set INVENTORY_SYNC_TOKEN="$(openssl rand -hex 32)" fly deploy

Connect Claude

In Claude (mobile or web), add a custom connector:

  • URL: https://.fly.dev/mcp

The /mcp endpoint currently has no authentication — anyone with the URL can
call tools. Use the obscurity of the URL plus Fly's network controls for now;
add per-user auth before sharing the URL.

Environment variables

Variable Required Purpose
INVENTORY_SYNC_TOKEN for /inventory Bearer token protecting GET/POST /inventory; when unset, sync returns 503
INVENTORY_PATH no Path to inventory.json; default ~/.minipainting/inventory.json locally, /data/inventory.json in the Docker image
INVENTORY_JSON no One-time seed JSON; only used when INVENTORY_PATH is absent on first boot
WARPAINT_INVENTORY_JSON no Legacy alias of INVENTORY_JSON
MCP_SERVER_NAME no Server name in MCP handshake + startup log; default paint-inventory
PORT no (default 3000) TCP port to listen on

Known limitations

  • /mcp has no authentication yet. The bearer token only protects /inventory.
  • Stateless transport: no long-running SSE tool streams (the tools are
    fast so this is fine).

Self-hosting your own MCP

The MCP server is generic — only the CLI (mpaint) is branded. To run your
own instance:

  1. Fork or clone the repo.
  2. (Optional) rename your Fly app in fly.toml.
  3. Create a Fly volume and set secrets:bash fly volumes create inventory_data --size 1 --region <your-region> fly secrets set INVENTORY_SYNC_TOKEN=$(openssl rand -hex 24) # Optional one-time seed: fly secrets set INVENTORY_JSON="$(cat ~/.minipainting/inventory.json)"

  4. (Optional) name your MCP server (shown in the MCP handshake and startup
    logs):bash fly secrets set MCP_SERVER_NAME=my-paints

  5. Deploy:bash fly deploy

  6. Register the remote in your local CLI and sync:bash mpaint sync add default \ --url https://my-app.fly.dev \ --token <token-from-step-3> mpaint sync push

After this, your local inventory and the deployed MCP stay in sync via
mpaint sync push (upload local → remote) and mpaint sync pull --force
(overwrite local from remote).

License

MIT © Artur Skowronski

常见问题

7 问
答案由本站依据条目字段整理,不引用上游原文
Minipainter 怎么安装?

资料没有给出安装命令,请到官方仓库或文档按说明接入;这类条目多数是生态应用,或尚未发布可安装包。

Minipainter 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式未标注,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Minipainter 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Minipainter 需要 API Key 吗?

资料标注需要API Key认证,使用前准备好对应凭据,并按最小权限配置。

Minipainter 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor、Codex、Zed;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Minipainter 能提供哪些能力?

资料显示能力标签包括 cli、local first。具体工具清单以官方文档为准。

Minipainter 需要什么运行环境?

运行时为 node。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 未标注。