iccdev-mcp

MCP server for ICC color profile tools from the International Color Consortium's RefIccMAX (iccDEV) library.

Exposes tools to AI assistants (Claude, Copilot, Cursor) via the Model Context Protocol, covering profile inspection, color transforms, and format conversion for ICC v2/v4 and iccMAX v5 profiles.

The static MCP inventory lists supported tools; health_check reports the tools available in the running environment. Optional native capabilities can differ between container variants, so clients and CI must inspect capability flags and the discovered CLI inventory rather than assume a fixed health-tool total. The response includes the available native, CLI, and service inventories so clients can derive its dynamic total_tools value without numeric assumptions.

Install

For the lowest-friction setup, use the unified iccDEV Docker image. It includes the MCP server, REST dependencies, CLI tools, runtime libraries, maintainer utilities, and Testing/ profiles, so no local iccDEV build is required.

docker run --rm -i ghcr.io/internationalcolorconsortium/iccdev:latest \
  iccdev-mcp-entrypoint mcp

Use pip install when integrating with a local source checkout or a locally built iccDEV toolchain. iccdev-mcp is published on PyPI:

python -m pip install "iccdev-mcp[rest]"

The universal wheel from a successful rolling Latest Build remains available for exact-tag installation:

# Replace <release-tag> with the Git tag for the intended release.
python -m pip install "git+https://github.com/InternationalColorConsortium/iccDEV.git@<release-tag>#subdirectory=iccdev-mcp"
# Prebuilt GitHub release wheel; copy its exact tag-specific asset URL.
python -m pip install "<iccdev_mcp-wheel-asset-URL>"
# Optional REST server dependencies:
python -m pip install "iccdev-mcp[rest] @ <iccdev_mcp-wheel-asset-URL>"

Release assets include one iccdev_mcp-*-py3-none-any.whl and a matching source distribution for Python 3.10+. Verify their published checksums and provenance before installation. The release workflow tests source imports, isolated wheel and sdist installations, console entry points, stdio tool calls, and REST health on Windows and Linux. It includes no native binaries or compiled transform bindings. See the package release guide for maintainer validation and the PyPI publication boundary.

For an isolated MCP client, use the public package directly:

{
  "mcpServers": {
    "iccdev": {
      "command": "uvx",
      "args": ["iccdev-mcp"]
    }
  }
}

Use uvx --from "<iccdev_mcp-wheel-asset-URL>" iccdev-mcp when an exact GitHub release asset is required instead of the PyPI package.

The wheel ships only the iccdev_mcp namespace, so it can share an environment with the separate Cython iccdev bindings. Header inspection and signature helpers are included. Pixel transforms require installing the native bindings from python/ in the same environment. The validate_profile tool dynamically loads the public C validation ABI, so it also needs a shared IccProfLib build. CLI-backed tools require iccDEV CLI binaries. Build iccDEV locally or set ICCDEV_TOOLS_DIR and ICCDEV_BUILD_DIR to an existing build. The REST health endpoint reports the bundled Python API and CLI discovery separately, so incomplete local builds are visible at startup.

# Point to compiled iccDEV tools
export ICCDEV_TOOLS_DIR=/path/to/iccDEV/Build/Tools
export ICCDEV_BUILD_DIR=/path/to/iccDEV/Build

Usage

Docker

The unified image uses a shell default. Start an MCP transport explicitly:

# MCP stdio mode
docker run --rm -i ghcr.io/internationalcolorconsortium/iccdev:latest \
  iccdev-mcp-entrypoint mcp

# REST API mode on http://127.0.0.1:8080
docker run --rm -p 127.0.0.1:8080:8080 \
  ghcr.io/internationalcolorconsortium/iccdev:latest \
  iccdev-mcp-entrypoint rest

Open http://127.0.0.1:8080/ for the bundled REST dashboard. The dashboard groups MCP-backed API routes, shows REST-only utility routes such as file browsing and upload, and runs tools without requiring a separate client.

Supported container modes are mcp/stdio, rest/api, sse, and streamable-http/http.

Useful runtime defaults are already configured:

The unified image keeps sanitizer CLI tools, but loads the validation ABI from an isolated non-sanitized shared build. An explicit validation library overrides ICCDEV_BUILD_DIR, including the image default above. To select a custom build, override this library path or unset it before starting the server. Empty, missing, and unloadable explicit library paths fail closed without silently falling back. Pip-only installations retain optional validation behavior.

Mount additional profiles read-only and list them through ICCDEV_PROFILE_DIRS:

docker run --rm -p 127.0.0.1:8080:8080 \
  -v "$PWD/profiles:/profiles:ro" \
  -e ICCDEV_PROFILE_DIRS=/profiles \
  ghcr.io/internationalcolorconsortium/iccdev:latest \
  iccdev-mcp-entrypoint rest

Local build and smoke test:

docker build -t iccdev:mcp-local -f Dockerfile .
docker run --rm -p 127.0.0.1:8080:8080 \
  iccdev:mcp-local iccdev-mcp-entrypoint rest
curl -fsS http://127.0.0.1:8080/api/health
curl -fsS http://127.0.0.1:8080/api/tools
python3 .github/scripts/iccdev-container-smoke.py iccdev:mcp-local
# Optional REST dashboard in a browser
xdg-open http://127.0.0.1:8080/  # or open the URL manually

Claude Desktop

For a container-only local client, use this unified image configuration. Keep -i (open stdin), omit -t, and do not close stdin until requested tool responses arrive:

{
  "mcpServers": {
    "iccdev": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
               "ghcr.io/internationalcolorconsortium/iccdev:latest",
               "iccdev-mcp-entrypoint", "mcp"]
    }
  }
}

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "iccdev": {
      "command": "iccdev-mcp",
      "env": {
        "ICCDEV_TOOLS_DIR": "/path/to/iccDEV/Build/Tools"
      }
    }
  }
}

VS Code (Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "iccdev": {
      "command": "iccdev-mcp"
    }
  }
}

GitHub Copilot coding agent

Add this repository MCP configuration under Settings -> Copilot -> MCP servers. GitHub requires explicit type, args, and tools fields for repository MCP settings.

{
  "mcpServers": {
    "iccdev": {
      "type": "local",
      "command": "iccdev-mcp",
      "args": [],
      "env": {
        "ICCDEV_TOOLS_DIR": "Build/Tools"
      },
      "tools": [
        "inspect_header",
        "profile_summary",
        "validate_profile",
        "color_transform",
        "roundtrip_delta",
        "icc_sig_to_str",
        "enum_spaces",
        "list_available_profiles",
        "health_check",
        "dump_profile",
        "profile_to_xml",
        "xml_to_profile",
        "profile_to_json",
        "json_to_profile",
        "tiff_dump",
        "jpeg_dump",
        "png_dump",
        "heif_dump",
        "from_cube",
        "apply_profiles",
        "apply_named_cmm",
        "create_link",
        "v5_to_v4",
        "spec_sep_to_tiff",
        "apply_search",
        "round_trip_test",
        "pawg_report"
      ]
    }
  }
}

Remote (SSE transport)

iccdev-mcp --transport sse --port 8080

Tools

Python-Native

CLI-Backed -- require iccDEV tools

CLI-Only Tools (Not MCP-Exposed)

The following built iccDEV executables do not have MCP wrappers and must not be added to an MCP server tools allowlist: iccBenchApply, iccProfilePlot, iccProfileVisualize, and iccProfileVisualizePlot. Use them directly from the command line; see the repository CLI tool reference for their interfaces.

Utility (2)

The REST dashboard at / and /ui provides Testing/ directory and filename selectors for ICC, XML, JSON, TIFF, JPEG, PNG, HEIF, HEIC, AVIF, and cube inputs. /api/tools returns the stable MCP inventory and separately lists REST-only utility routes (/api/tools, /api/files, and /api/upload). Core CLI-backed forms expose documented options for iccDumpProfile validation/verbosity/tag selection, iccPawgReport profile assessment, iccRoundTrip intent/MPE selection, and iccApplyProfiles structured or raw -cfg argument mode.

Environment Variables

Development

# Install for development
cd iccdev-mcp
pip install -e ".[dev,rest]"

# Run tests
pytest tests/ -v

# Run server (stdio)
python -m iccdev_mcp.server

License

BSD 3-Clause. See LICENSE.md.