使用说明

Mimi Panda MCP Server

A Model Context Protocol (MCP) server that provides seamless access to the Mimi Panda API, enabling AI assistants like Claude to interact with coloring pages, paint by numbers, AI image generation, and image processing services.

Features

🎨 Coloring Pages: Convert images into coloring pages with various styles
🖼️ Paint by Numbers: Generate paint-by-numbers images from photos or prompts
⬇️ PBN Downloads: Download finished PBN images (SVG, PNG, PDF) and color palettes (PDF, JPEG, CSV, Procreate, GIMP, Krita) directly via API
🤖 AI Image Generation: Create images from text prompts
🎭 AI Filters: Apply artistic filters to images
📈 Image Upscaling: Enhance and upscale images up to 4x
🔐 Authentication: Built-in support for API token authentication
📋 Route Discovery: List and explore available API endpoints

Prerequisites

Node.js 18+ (required by @modelcontextprotocol/sdk)
Access to the Mimi Panda API (either self-hosted or cloud instance)

Installation

# Clone the repository
git clone https://github.com/mimipanda/mcp-server.git
cd mcp-server

# Install dependencies
npm install

Configuration

The server can be configured using environment variables. Copy .env.example to .env and update with your values, or set them in your environment:

Variable	Purpose	Default
`MCP_API_BASE_URL`	Base URL for the Mimi Panda API endpoint (e.g. `https://mimi-panda.com`)	`http://localhost`
`MCP_API_PREFIX`	API prefix appended to every request	`/api`
`MCP_API_TOKEN`	Optional default Bearer token for authenticated routes (can be retrieved later via `auth/login`)	unset
`MCP_API_HEADERS`	JSON object with extra headers (e.g. `{"X-Api-Key":"secret"}`)	`{}`
`MCP_API_TIMEOUT`	Request timeout in milliseconds (1000–120000)	`60000`

Example `.env` file

Copy .env.example to .env and customize:

cp .env.example .env

Then edit .env with your values (you can leave MCP_API_TOKEN blank until you obtain one from the auth APIs):

MCP_API_BASE_URL=https://mimi-panda.com
MCP_API_PREFIX=/api
MCP_API_TOKEN=your-api-token-here
MCP_API_TIMEOUT=60000

Obtain your API token by logging into the Mimi Panda application (web or desktop) and copying the token from your account settings. Store the token in .env or supply it per request once you have it.

Usage

Running the Server

The MCP server communicates via STDIO and is designed to be used with MCP-compatible clients like Claude Desktop.

# Run directly
npm start

# Or with node
node src/mcp-server.mjs

Claude Desktop Configuration

Add the server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mimi-panda": {
      "command": "node",
      "args": ["/path/to/mcp-server/src/mcp-server.mjs"],
      "env": {
        "MCP_API_BASE_URL": "https://mimi-panda.com",
        "MCP_API_PREFIX": "/api",
        "MCP_API_TOKEN": "your-token-here"
      }
    }
  }
}

After adding the configuration, restart Claude Desktop to connect to the server.

Available Tools

The server exposes two main tools:

1. `list_api_routes`

List all available API routes with their descriptions, authentication requirements, and schemas.

Each route in the response includes structured metadata (types, descriptions, enum values, nested objects) and the plaintext summary now lists every field and its allowed values, so MCP clients can see accepted parameters before issuing a request.

Parameters:

filter (optional): Case-insensitive filter for method, path, or description
group (optional): Filter by logical group (auth or service)

Example:

List all routes in the "service" group

2. `call_api`

Perform HTTP requests to any Mimi Panda API endpoint.

Parameters:

method (default: GET): HTTP method (GET, POST, PUT, PATCH, DELETE)
path: API path relative to the prefix (e.g., service/coloring)
query (optional): Query string parameters
body (optional): Request payload (objects/arrays are JSON-encoded)
token (optional): Bearer token (uses MCP_API_TOKEN if omitted)

Leave the environment variable empty until you copy an API token from the Mimi Panda application; once you have it, set the value in .env or pass it per-request.
headers (optional): Additional headers
timeoutMs (optional): Request timeout override (max 120000ms)

Example:

Call the coloring API with an image URL

LLM token workflow: Sign up and log in through the Mimi Panda application first, then copy your API token into .env or pass it via the token field. The MCP server will continue to manage the Bearer prefix automatically, but it no longer provisions accounts or tokens on its own.

API Endpoints

The server provides access to the following Mimi Panda API endpoints:

Authentication

POST /api/auth/login - Authenticate and receive API token
GET /api/user/me - Get authenticated user profile
POST /api/user/logout - Invalidate current token

Accounts must now be created and authenticated inside the Mimi Panda application. After logging in there, copy the API token from your profile before using this MCP server.

Services

POST /api/service/coloring - Create coloring pages from images
POST /api/service/pbn - Generate paint-by-numbers images

Optional minArea: number from 0 to 100 in 0.1 increments (e.g. 0, 1.5, 2.3) or the string "auto" (default). Non-commercial accounts are clamped to a minimum of 1.5 server-side.

Optional cleanup filters: thinLineWidth (integer 1–30 px, default 1) absorbs hairline ridges into surrounding zones; colorMergeThreshold (integer 0–100, default 0) merges adjacent zones with similar colors (0 disables); thinZoneMerge (integer 3–50 px, default 3) merges zones too narrow to hold a painted number.
POST /api/service/ai/coloring - Generate AI coloring pages from a text prompt, optionally guided by a reference image

Optional image: multipart file or public URL (jpg, png, webp, jpeg, heic, heif; max 20MB). Prompt is still required. When image is set, generation is image-to-image (subject stays recognizable; output size follows the reference, longest side ≤ 2048px; aspectRatio is ignored). Use multipart/form-data when uploading a file.
POST /api/service/ai/name-coloring - Generate name coloring pages from a name with font style and decorative elements
POST /api/service/ai/image - Generate AI images from a text prompt, optionally guided by a reference image

Optional image: multipart file or public URL (jpg, png, webp, jpeg, heic, heif; max 20MB). Prompt is still required. When image is set, generation is image-to-image (subject stays recognizable; output size follows the reference, longest side ≤ 2048px). aspectRatio remains required by validation but is ignored for output dimensions. Use multipart/form-data when uploading a file.
POST /api/service/image/upscale - Upscale images (2x or 4x)
POST /api/service/image/filter - Apply AI filters to images
GET /api/service/items - List the authenticated user's generated items (paginated)

Optional query params: type (coloring, pbn, ai_coloring, ai_image, name_coloring, upscale, ai_filter), status (in_queue, processing, ready, failed), page (default 1), per_page (default 24, max 100). Returns a slim list (key, type, status, created, title, thumbnail); use GET /api/service/item/{uuid} for full detail. type values are public API names (not internal DB types). thumbnail is null until status is ready. Banned items are excluded from the list and cannot be filtered via ?status=banned.

Example (mobile PBN gallery): GET /api/service/items?type=pbn&status=ready&page=1&per_page=24
GET /api/service/item/{uuid} - Retrieve task results by UUID. Response includes top-level type (same public enum as the list endpoint). Terminal statuses: ready, failed, banned. A banned item includes a localized error message when content moderation blocked the generated image.

PBN Downloads

Once a PBN item status is ready, download its files directly:

GET /api/service/item/{uuid}/pbn/download/{type} - Download a PBN image file

Supported type values: pbn, origin, source, outlines, outlinespng, grayscale, grayscalepng, pbnpng, originpng, originwithnumbers, custom, pbnpdf, outlinespdf, grayscalepdf, originpdf

Optional query params: width, height (pixels, for PNG/PDF types). The custom type requires additional download-type, download-strokes-color, and download-numbers-color query params.
GET /api/service/item/{uuid}/pbn/colors/{type} - Download the PBN color palette

Supported type values: pdf, pdfshort, png, pngshort, csv, swatches, gpl, kpl

For type=swatches, the backend may return either:
- a single .swatches file when the palette has 30 colors or fewer
- a .zip archive containing multiple .swatches files when the palette has more than 30 colors
Detect which one you received using the Content-Disposition filename and the X-Mimi-Colors-Format response header (swatches or zip).

Color Tools

POST /api/service/color/unmix - Unmix a color into its primary and secondary paint components

Body: { "hex": "a3c2f0" }. Returns hex, rgb, hsl, plus unmix (secondary breakdown) and unmix_primary (primary breakdown) — each a map of pigment name → proportion.
POST /api/service/color/mix - Mix 2–4 colors into a single blended result using the Spectral physically-based paint model (Kubelka-Munk)

Body: { "colors": [{ "hex": "ff0000", "amount": 2 }, { "hex": "ffff00", "amount": 1 }] }. amount is a relative weight (defaults to equal). Returns a single { "hex", "rgb", "hsl" } object.

VAL / Virtual Artist Lab

Commercial plan only (canAccessValApi). Only the authenticated user's private palettes are exposed — brand/public palettes are never returned.

Private palettes

GET /api/service/val/palettes - List private palettes
POST /api/service/val/palettes - Create a private palette

Body: { "palette_name": "My Palette", "colors": [{ "hex": "ff0000" }] }. colors optional (max 100).
GET /api/service/val/palettes/{id} - Get a private palette (colors + options)
DELETE /api/service/val/palettes/{id} - Delete a private palette
PUT /api/service/val/palettes/{id}/options - Update palette options

Body: { "printCodes": true }
POST /api/service/val/palettes/{id}/colors - Add a color
PUT /api/service/val/palettes/{id}/colors/{colorId} - Edit a color
DELETE /api/service/val/palettes/{id}/colors/{colorId} - Delete a color (remaining colors are re-indexed)
GET /api/service/val/palettes/{id}/download/{type} - Download palette as a file

Supported type values: swatches, gpl, kpl, pdf, pdf-short, image, image-short, csv, css, tailwind, json, svg

Without Premium, only css, tailwind, and json are allowed. Palettes with more than 200 colors cannot export PDF/swatches/image types.

Color tools

POST /api/service/val/color/details - Color details + primary/secondary unmix (no brand similar colors)

Body: { "hex": "a3c2f0" }
POST /api/service/val/mix/chart - Spectral mix chart matrix for 2–10 colors

Body: { "colors": ["ff0000", "ffff00", "0000ff"], "include_diagonal": true }
POST /api/service/val/color/match - Match a target hex against a private palette or inline colors

Body requires hex plus either palette_id or colors (1–40). Optional limit (1–50, default 20) and max_components (1–3, default 3).
POST /api/service/val/color-simplifier - Quantize an image to N colors (multipart; returns PNG)
POST /api/service/val/grid - Overlay a drawing grid on an image (multipart; returns image)

gridType: 3x3, 4x4, or square (with optional squareCells: 4|6|8|10|12).
POST /api/service/val/outlines - Convert an image to a printable black-and-white outline (multipart; returns PNG)

mode: fast, detailed, or clean. Optional showGrid + gridSize (3 or 4).
POST /api/service/val/tonal-values - Convert an image to a light/midtone/shadow study or color map (multipart; returns PNG)

mode: light, midtone, shadow, or colorMap.
GET /api/service/val/mimi-panda-palette/similar - Nearest Mimi Panda palette colors for a hex

Query: ?hex=a3c2f0. Returns at most 10 nearest colors — the full Mimi Panda palette catalog is not exposed.

For detailed parameter information, use the list_api_routes tool.

Development

Project Structure

mcp-server/
├── src/
│   ├── mcp-server.mjs          # Main server implementation
│   └── mcp-ai-filter-types.json # AI filter type definitions
├── .github/                    # GitHub templates and workflows
├── .gitignore
├── .npmignore
├── .env.example                # Sample environment configuration
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
├── PRODUCTION_CHECKLIST.md
├── package.json
├── package-lock.json
└── README.md

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues, questions, or contributions, please open an issue on GitHub.

Related Projects

Model Context Protocol - The protocol specification
MCP SDK - Official MCP SDK

Made with ❤️ by Slava R. and Ira R. - Mimi Panda team