Graphics MCP Server

Unified MCP server for raster image inspection, conversion, and manipulation.

Version: 0.2.0 Status: Internal Bodai integration component

Quick Links

• Overview
• Capabilities
• Quick Start
• MCP Server Configuration
• Tool Reference
• Configuration
• Development

Quality & CI

Crackerjack is the standard quality-control and CI/CD gate for Graphics MCP changes. Local verification should mirror the Crackerjack workflow used across the Bodai ecosystem.

Overview

Graphics MCP exposes common image operations through a FastMCP server. It gives agents a bounded way to inspect image metadata, convert formats, resize, crop, rotate, flip, thumbnail, and apply filters while keeping filesystem access constrained to configured directories.

The current implementation uses the Pillow backend. The settings model already reserves flags for ImageMagick and GIMP backends, but those should be treated as future or optional surfaces unless validated for the target deployment.

Capabilities

Implemented tool surface:

• Image inspection: read dimensions, format, mode, and file metadata
• Format conversion: convert among JPEG, PNG, GIF, BMP, WEBP, and TIFF
• Resize and crop: fit, fill, exact, and crop-oriented raster transformations
• Filter operations: blur, sharpen, grayscale, sepia, invert, contrast, brightness, and related effects
• Orientation operations: rotate and flip images
• Thumbnail generation: create bounded thumbnails from source images
• Filesystem guardrails: list and enforce configured allowed directories and maximum file size
• HTTP health routes: /health and /healthz for MCP client and process supervision checks

Quick Start

Prerequisites

• Python 3.13+
• UV package manager
• Local image files under an allowed directory

Local Setup

git clone https://github.com/lesleslie/graphics-mcp.git
cd graphics-mcp
uv sync --group dev

Run The Server

uv run graphics-mcp start
uv run graphics-mcp health

The default HTTP bind is 127.0.0.1:3040.

Allow A Working Directory

export GRAPHICS_ALLOWED_DIRECTORIES="/tmp,/Users/les/Pictures,/Users/les/Downloads"
uv run graphics-mcp start

CLI Commands

The CLI is built with mcp-common and provides the standard lifecycle command surface used by Bodai MCP servers.

uv run graphics-mcp start      # Start the HTTP MCP server
uv run graphics-mcp stop       # Stop the managed server process
uv run graphics-mcp restart    # Restart the managed server process
uv run graphics-mcp status     # Show process status
uv run graphics-mcp health     # Run the local health probe

MCP Server Configuration

Claude / Codex Style Configuration

Add the server to an MCP client configuration:

{
  "mcpServers": {
    "graphics": {
      "command": "uv",
      "args": ["run", "graphics-mcp", "start"],
      "cwd": "/Users/les/Projects/graphics-mcp",
      "env": {
        "GRAPHICS_ALLOWED_DIRECTORIES": "[\"/tmp\", \"/Users/les/Pictures\", \"/Users/les/Downloads\"]"
      }
    }
  }
}

Health Checks

curl http://127.0.0.1:3040/health
curl http://127.0.0.1:3040/healthz

Tool Reference

Tool responses follow a consistent ToolResponse shape:

{
  "success": true,
  "message": "Image converted successfully",
  "data": {},
  "error": null,
  "next_steps": []
}

Configuration

Committed defaults live in settings/graphics.yaml. Runtime overrides should come from environment variables or a local .env file that is not committed.

Project Structure

graphics_mcp/
  backends/          # Backend interface and Pillow implementation
  cli.py             # mcp-common lifecycle CLI
  config.py          # Pydantic settings and logging
  models.py          # Typed image operation models
  server.py          # FastMCP application factory
  tools/             # Universal and raster MCP tools
settings/
  graphics.yaml      # Committed defaults
tests/

Development

uv sync --group dev
uv run pytest
uv run ruff check graphics_mcp tests
uv run ruff format graphics_mcp tests
uv run mypy graphics_mcp

Use targeted tests when isolating a backend or tool behavior:

uv run pytest tests -k resize -v

Security Notes

• Keep image file access constrained with GRAPHICS_ALLOWED_DIRECTORIES.
• Do not add tools that write outside configured paths.
• Treat user-provided image paths as untrusted input.
• Avoid logging full sensitive local paths when examples are shared outside local development.