使用说明

Graphics MCP Server

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

Version: 0.2.0 Status: Standalone FastMCP server

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.

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.

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

Installation via Claude Code marketplace

This repo ships a Claude Code plugin manifest (.claude-plugin/plugin.json) plus a colocated .mcp.json and three slash commands in commands/. To install, register the www-mcp-servers marketplace with Claude Code, then install the plugin by name. Once installed, the slash commands /graphics-convert, /graphics-resize, and /graphics-thumbnail become available alongside the mcp__graphics__* tools.

Tool Reference

Tool	Purpose	Key Inputs
`get_image_info`	Inspect image metadata	`image_path`
`convert_image`	Convert an image to another format	`image_path`, `output_format`
`resize_image`	Resize an image by width, height, and mode	`image_path` (required); `width` XOR `height`
`crop_image`	Crop an image to pixel boundaries	`image_path`, `left`, `top`, `right`, `bottom`
`apply_filter`	Apply a raster filter effect	`image_path`, `filter_type`
`rotate_image`	Rotate an image by degrees	`image_path`, `degrees`
`flip_image`	Flip horizontally or vertically	`image_path`
`create_thumbnail`	Create a thumbnail within max dimensions	`image_path`, `width`, `height`
`list_available_filters`	List supported filter names	none
`list_allowed_directories`	Show configured filesystem guardrails	none
`list_supported_formats`	Show supported image formats	none

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.

Setting	Environment Variable	Default
Default backend	`GRAPHICS_DEFAULT_BACKEND`	`pillow`
Enable Pillow	`GRAPHICS_ENABLE_PILLOW`	`true`
Enable ImageMagick	`GRAPHICS_ENABLE_IMAGEMAGICK`	`false`
Enable GIMP	`GRAPHICS_ENABLE_GIMP`	`false`
Allowed directories	`GRAPHICS_ALLOWED_DIRECTORIES`	`/tmp`, `~/Pictures`, `~/Downloads`
Max file size	`GRAPHICS_MAX_FILE_SIZE_MB`	`100`
Allowed formats	`GRAPHICS_ALLOWED_FORMATS`	`JPEG`, `PNG`, `GIF`, `BMP`, `WEBP`, `TIFF`
Enable HTTP transport	`GRAPHICS_ENABLE_HTTP_TRANSPORT`	`false`
HTTP host	`GRAPHICS_HTTP_HOST`	`127.0.0.1`
HTTP port	`GRAPHICS_HTTP_PORT`	`3040`
Log level	`GRAPHICS_LOG_LEVEL`	`INFO`
JSON logs	`GRAPHICS_LOG_JSON`	`true`

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.

Built on Oneiric for runtime configuration and mcp-common for the FastMCP baseline. Crackerjack gates every commit.