<div align="center">

# mcp-print

**Professional print & color workflow tools for AI assistants**

[![PyPI version](https://img.shields.io/pypi/v/mcp-print.svg)](https://pypi.org/project/mcp-print/)
[![Python](https://img.shields.io/pypi/pyversions/mcp-print.svg)](https://pypi.org/project/mcp-print/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/kcgdz/mcp-print/actions/workflows/ci.yml/badge.svg)](https://github.com/kcgdz/mcp-print/actions/workflows/ci.yml)

2400+ Pantone colors &bull; CMYK/RGB conversion &bull; Ink & cost estimation &bull; ICC profiles &bull; Spot color separation &bull; Barcode coverage &bull; Delta E &bull; Paper weights &bull; Preflight checks &bull; Substrate simulation &bull; Imposition &bull; Booklet & spine calculation &bull; Lab conversion &bull; CIEDE2000 &bull; TAC/GCR &bull; Dot gain compensation &bull; PDF preflight &bull; Job quoting

**Works 100% offline &mdash; no API keys needed**

[Install](#install) &bull; [Configure](#configure-with-claude-code) &bull; [Tools](#tools) &bull; [Examples](#usage-examples) &bull; [Contributing](#development)

Backed by [optiraj.com](https://optiraj.com) — SaaS for print professionals

</div>

---

## Who is this for?

| Role | Use case |
|---|---|
| **Print designers** | Check Pantone-to-CMYK conversions without leaving your editor |
| **Prepress engineers** | Estimate ink costs, verify color accuracy (Delta E), analyze ICC profiles, run preflight checks |
| **Packaging teams** | Convert paper weights, separate spot vs process colors, cost entire print runs, simulate substrate shifts |
| **Brand managers** | Find the closest Pantone match to any HEX color |

## Install

```bash
pip install mcp-print
```

> Requires Python 3.10+. Zero external dependencies beyond the [MCP SDK](https://pypi.org/project/mcp/).

## Configure with Claude Code

Add to your Claude Code MCP config (`~/.claude/settings.json` or project `.mcp.json`):

```json
{
  "mcpServers": {
    "print": {
      "command": "python",
      "args": ["-m", "mcp_print"]
    }
  }
}
```

Restart Claude Code — all twenty tools will be available immediately.

## Tools

### Color & Pantone

| Tool | Description |
|---|---|
| `pantone_to_cmyk_tool` | Convert a Pantone name to CMYK + HEX. Fuzzy matching — `"485C"`, `"pantone 485"`, `"Warm Red"` all work |
| `pantone_search_tool` | Find the closest Pantone colors to any HEX or CMYK value (top N matches by Delta E) |
| `cmyk_to_rgb_tool` | Convert CMYK values (0-100) to RGB (0-255) + HEX |
| `rgb_to_cmyk_tool` | Convert RGB (0-255) or HEX to CMYK values (0-100) |
| `color_delta_e_tool` | Calculate Delta E (CIEDE2000 or CIE76) between two CMYK colors with quality interpretation |
| `lab_convert_tool` | Convert between CIELAB (spectrophotometer readings), CMYK, RGB, and HEX |
| `spot_color_separator_tool` | Given a list of design colors, recommend which should be spot vs process |

### Print Production

| Tool | Description |
|---|---|
| `ink_consumption_tool` | Estimate ink grams/kg and cost for a print run (offset, flexo, gravure, screen, digital) |
| `print_cost_estimator_tool` | Full job cost breakdown: ink + plates + makeready + run cost |
| `barcode_ink_coverage_tool` | Ink coverage % for Code 128, EAN-13, QR, and Data Matrix barcodes |
| `preflight_check_tool` | Pre-press file validation — checks color mode, resolution, bleed, fonts, ink coverage, and transparency |
| `substrate_simulator_tool` | Simulate CMYK color shifts on different paper substrates (dot gain, absorption, tint) |
| `imposition_calculator_tool` | N-up imposition — how many pieces fit on a press sheet, sheets needed, utilization % |
| `booklet_calculator_tool` | Signature count, page rounding, and spine thickness for saddle-stitch or perfect-bound booklets |
| `dot_gain_compensation_tool` | File CMYK values that hit target tints on press — inverse of substrate simulation |
| `ink_limit_check_tool` | Total ink coverage (TAC) check with automatic GCR reduction |
| `full_job_quote_tool` | Imposition + sheet-based costing in one call, with local prices in any currency |
| `pdf_preflight_tool` | Preflight a real PDF file: trim/bleed boxes, font embedding, image color spaces (`pip install mcp-print[pdf]`) |

### Utilities

| Tool | Description |
|---|---|
| `icc_profile_info_tool` | Parse ICC/ICM profile metadata (color space, device class, version, PCS) from any `.icc` file |
| `paper_weight_converter_tool` | Convert between GSM, lb text, and lb cover |

## Usage Examples

Once configured, just ask Claude naturally:

---

### Pantone Lookup

> *"What's the CMYK breakdown for Pantone 485 C?"*

Fuzzy matching accepts any format: `"485C"`, `"pantone 485"`, `"485 coated"`, `"Warm Red"`

```json
{ "name": "Pantone 485 C", "c": 0, "m": 95, "y": 100, "k": 0, "hex": "#FF0D0D" }
```

<img src="cmyk.png" alt="Pantone CMYK lookup example" width="700">

---

### Reverse Pantone Search

> *"What Pantone colors are closest to #DA291C?"*

```json
{
  "matches": [
    { "name": "Pantone 485 C", "c": 0, "m": 95, "y": 100, "k": 0, "hex": "#FF0D0D" },
    { "name": "Pantone 485 M", "c": 1, "m": 93, "y": 99, "k": 2, "hex": "#FA0E03" }
  ],
  "search_type": "hex #DA291C"
}
```

---

### Color Conversion

> *"Convert CMYK 100/44/0/0 to RGB"*

```json
{ "r": 0, "g": 143, "b": 255, "hex": "#008FFF" }
```

---

### Ink Estimation

> *"How much ink for 10,000 A4 flyers at 35% coverage on offset?"*

```json
{ "ink_grams": 327.44, "ink_kg": 0.3274, "cost_estimate_usd": 8.19 }
```

---

### Full Print Job Costing

> *"Cost estimate: 5,000 A4 flyers, 4-color offset, 120gsm, double-sided"*

```json
{
  "total_cost": 628.14,
  "cost_per_unit": 0.1256,
  "currency": "USD",
  "breakdown": {
    "ink": 11.34,
    "plates": 280.00,
    "makeready": 200.00,
    "run_cost": 136.80,
    "paper": 0.0
  }
}
```

Prices default to USD industry averages — pass your own ink/plate/makeready/run/paper prices in any currency for a localized quote.

---

### Color Matching QC

> *"Compare brand blue (100/72/0/18) vs proof (98/70/2/20) — is the Delta E acceptable?"*

```json
{ "delta_e": 3.41, "interpretation": "fair — noticeable difference" }
```

| Delta E | Quality |
|---|---|
| < 1 | Excellent — imperceptible |
| 1 - 3 | Good — barely perceptible |
| 3 - 6 | Fair — noticeable |
| > 6 | Poor — obvious difference |

---

### Spot vs Process Recommendation

> *"Should these colors be spot or process?"*

```json
{
  "spot_colors": [
    { "nearest_pantone": "Pantone 485 C", "delta_e": 0.0, "reason": "Close match — use spot for accuracy" }
  ],
  "process_colors": [
    { "nearest_pantone": "Pantone 375 C", "delta_e": 8.2, "reason": "No close match — reproduce as CMYK" }
  ]
}
```

---

### ICC Profile Inspection

> *"What color space does this ICC profile use?"*

```json
{
  "profile_name": "ISOcoated_v2",
  "color_space": "CMYK",
  "device_class": "Output (Printer)",
  "version": "2.4.0",
  "pcs": "XYZ"
}
```

---

### Barcode Ink Coverage

> *"Ink coverage for an EAN-13 barcode at 37mm x 26mm?"*

```json
{
  "coverage_percent": 52.0,
  "recommended_ink": "Process Black (K: 100)",
  "print_method_suggestion": "offset — good resolution for medium modules"
}
```

<img src="ink.png" alt="Barcode ink coverage analysis example" width="700">

---

### Paper Weight Conversion

> *"What's 80 lb text in GSM?"*

```json
{ "value": 118.42, "from_unit": "lb_text", "to_unit": "gsm" }
```

---

### Preflight Check

> *"Validate my file for offset printing: CMYK, 300 DPI, 3mm bleed, fonts embedded"*

```json
{
  "status": "pass",
  "checks": [
    { "name": "color_mode", "status": "pass", "message": "CMYK is correct for offset." },
    { "name": "resolution", "status": "pass", "message": "300 DPI meets the minimum of 300 DPI for offset." },
    { "name": "bleed", "status": "pass", "message": "3.0 mm bleed meets the 3.0 mm minimum for offset." },
    { "name": "fonts", "status": "pass", "message": "All fonts are embedded." },
    { "name": "ink_coverage", "status": "pass", "message": "Total ink coverage 280% is within safe limits." },
    { "name": "transparency", "status": "pass", "message": "No transparency detected." }
  ],
  "summary": "6 passed, 0 warnings, 0 failed out of 6 checks.",
  "recommendation": "File is ready for production."
}
```

Checks color mode, resolution, bleed, font embedding, total ink coverage, and transparency against the target print method (offset, digital, flexo, gravure, screen).

| Check | Fail | Warning |
|---|---|---|
| Color mode | RGB/spot for offset/flexo/gravure/screen | RGB for digital |
| Resolution | Below 75% of method minimum | Below method minimum |
| Bleed | No bleed | Below method minimum |
| Fonts | Not embedded | — |
| Ink coverage | > 340% | > 300% |
| Transparency | — | Present (needs flattening) |

---

### Substrate Simulation

> *"How will CMYK 50/30/20/10 look on newsprint vs glossy coated?"*

```json
{
  "original": { "c": 50, "m": 30, "y": 20, "k": 10, "hex": "#73A1B8" },
  "simulated": { "c": 57.5, "m": 38.3, "y": 29.8, "k": 31.9, "hex": "#4A6B7A" },
  "substrate": "newsprint",
  "print_method": "offset",
  "adjustments": { "dot_gain_applied": 30, "absorption_k_added": 16.2 },
  "delta_e_from_original": 21.11,
  "warning": "Severe color shift — this substrate may not be suitable for color-critical work."
}
```

Six substrate profiles with different dot gain, absorption, and paper tint characteristics:

| Substrate | Dot gain (offset) | Tint | Typical use |
|---|---|---|---|
| `glossy_coated` | 12% | None | Magazines, brochures |
| `matte_coated` | 18% | Slight warm | Art books, reports |
| `uncoated` | 22% | Warm | Letterheads, books |
| `newsprint` | 30% | Yellow/gray | Newspapers, flyers |
| `kraft` | 25% | Strong brown | Packaging, bags |
| `recycled` | 25% | Slight gray | Eco-friendly prints |

---

### Imposition (N-up)

> *"How many A4 flyers fit on a 70x100 sheet, and how many sheets for 10,000?"*

```json
{
  "ups_per_sheet": 9,
  "layout": "3 x 3",
  "orientation": "normal",
  "sheets_needed": 1112,
  "sheets_with_waste": 1168,
  "sheet_utilization_percent": 84.1
}
```

Accounts for bleed, cutting gaps, and the gripper margin; tries both piece orientations and picks the best.

---

### Booklet & Spine Calculation

> *"48-page booklet on 90gsm uncoated with a 300gsm cover — signatures and spine?"*

```json
{
  "total_pages": 48,
  "signatures": 3,
  "total_sheets": 12,
  "spine_thickness_mm": 3.24,
  "binding": "saddle_stitch",
  "binding_note": "Suitable for saddle stitching."
}
```

Rounds pages to a multiple of 4, warns when the page count doesn't suit the chosen binding (saddle stitch > 64 pages, perfect bound < 3 mm spine).

---

## Pantone Database

The built-in database contains **2,415 Pantone colors**:

| Series | Range | Description |
|---|---|---|
| Numeric | 100–699 | Yellows, oranges, reds, pinks, purples, blues, greens, grays, browns |
| 7000 series | 7400–7547 | Extended gamut colors |
| Named | — | Black, White, Warm Red, Reflex Blue, Process Blue, Cool/Warm Grays 1–11, Hexachrome series |

Every color is available in three finishes: **Coated (C)**, **Uncoated (U)**, and **Matte (M)**.

Fuzzy matching handles format variations — `"485C"`, `"pantone 485"`, `"485 coated"` all resolve correctly.

## Development

```bash
git clone https://github.com/kcgdz/mcp-print.git
cd mcp-print
pip install -e .
pip install pytest
pytest tests/ -v
```

```
173 passed in 0.61s
```

## Acknowledgements

Development is supported by [Optiraj](https://optiraj.com) — a SaaS platform for print professionals. Optiraj sponsors open-source tooling that makes professional print knowledge freely accessible to the community.

## License

MIT