Image Filters MCP Server

A Model Context Protocol (MCP) server that provides 10 different image filters using Python and the Pillow library. This server implements the MCP protocol over STDIO, making it suitable for integration with Claude Desktop.

Features

• 10 Image Filters:
  • Grayscale - Convert the image to grayscale
  • Sepia - Apply a sepia tone effect
  • Blur - Apply Gaussian blur
  • Sharpen - Enhance image details
  • Edge Detection - Highlight edges
  • Invert Colors - Invert the image colors
  • Emboss - Create an embossed look
  • Contour - Detect image contours
  • Smooth - Smooth the image
  • Solarize - Apply a solarize effect

Project Structure

image_filters_mcp/           # Project root
├── server.py                # Main MCP server script (entry point)
├── tools/                   # Package for image filter functions
│   ├── __init__.py          # Makes tools a package
│   └── filters.py           # Contains all filter implementations
├── tests/                   # Contains test scripts
│   ├── test_filters.py      # Unit tests for filters
│   ├── test_server.py       # Integration tests for the server
│   └── create_test_image.py # Script to create test images
├── run_server.sh            # Script to run the server with venv
├── manual_test.py           # Script for manual testing
├── adding_new_filters.md    # Guide for adding new filters
├── claude_desktop_example.md # Guide for using with Claude Desktop
└── requirements.txt         # Python dependencies

Installation

1. Clone this repository:

   git clone https://github.com/rhish9h/image-filter-mcp.git
   cd image-filter-mcp
   

2. Create and activate a virtual environment:

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

Usage

Running the Server

Run the server directly:

./run_server.sh

Or manually:

source venv/bin/activate
python server.py

The server will wait for JSON-RPC input on STDIN and write responses to STDOUT.

Example Request Format

MCP uses the JSON-RPC 2.0 protocol. Here are examples of different request types:

Initialization

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize"
}

List Available Tools

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Call a Tool (Apply a Filter)

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "grayscale",
    "arguments": {
      "image_path": "path/to/input/image.jpg",
      "output_path": "path/to/output/image.jpg"
    }
  }
}

For filters with additional parameters (like blur or solarize), you can add them to the arguments object:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "blur",
    "arguments": {
      "image_path": "path/to/input/image.jpg",
      "output_path": "path/to/output/image.jpg",
      "radius": 5.0
    }
  }
}

Using the Manual Test Script

The repository includes a manual test script to easily test filters:

# Basic usage
python manual_test.py <filter_name> <input_image> <output_image> [param_name=param_value]

# Examples
python manual_test.py grayscale test_images/test_gradient.jpg output.jpg
python manual_test.py blur test_images/test_gradient.jpg output.jpg radius=5.0
python manual_test.py solarize test_images/test_gradient.jpg output.jpg threshold=100

Integration with Claude Desktop

To use this MCP server with Claude Desktop, update your Claude Desktop configuration file at ~/Library/Application Support/Claude/claude_desktop_config.json to include:

{
  "mcpServers": {
    "image-filters": {
      "command": "/path/to/venv/bin/python",
      "args": [
        "/path/to/image-filter-mcp/server.py"
      ]
    }
  }
}

See claude_desktop_example.md for more detailed instructions on using the server with Claude Desktop.

Testing

Creating Test Images

Create a test gradient image:

python tests/create_test_image.py

Running Unit Tests

Test the filter implementations:

python -m unittest tests/test_filters.py

Testing the Server

Test all filters with the test server script:

python tests/test_server.py

Extending the Server

This server is designed to be easily extensible. See adding_new_filters.md for a guide on how to add new filters to the system.

License

MIT