# 🎨 media-mcp-server

**MCP server for image & video processing. No API keys. No config. Just tools.**

Give your AI assistant the power to resize, convert, compress, crop, filter, and analyze images and videos — all through [Model Context Protocol](https://modelcontextprotocol.io/).

Works with **Claude Desktop**, **Claude Code**, **Cursor**, **VS Code**, **Windsurf**, and any MCP-compatible client.

---

## ⚡ Quick Start

### Claude Code
```bash
claude mcp add media-mcp -- uvx media-mcp-server
```

### Claude Desktop / Cursor / VS Code

Add to your MCP config:
```json
{
  "mcpServers": {
    "media-mcp": {
      "command": "uvx",
      "args": ["media-mcp-server"]
    }
  }
}
```

That's it. No API keys, no accounts, no environment variables.

---

## 🛠️ Tools

### Image Tools

| Tool | Description |
|------|-------------|
| `get_image_info` | Get dimensions, format, color mode, file size, EXIF data |
| `resize_image` | Resize by dimensions or scale factor with aspect ratio control |
| `convert_image` | Convert between PNG, JPEG, WebP, GIF, BMP, TIFF, ICO, AVIF |
| `compress_image` | Optimize file size with quality and max dimension controls |
| `crop_image` | Crop to specific pixel coordinates |
| `create_thumbnail` | Generate thumbnails with size control |
| `strip_metadata` | Remove all EXIF/metadata for privacy |
| `rotate_image` | Rotate by any angle with optional expansion |
| `flip_image` | Mirror horizontally or vertically |
| `apply_filter` | Apply blur, sharpen, grayscale, emboss, contour, and more |

### Video Tools (requires [ffmpeg](https://ffmpeg.org/download.html))

| Tool | Description |
|------|-------------|
| `get_video_info` | Get duration, resolution, codec, bitrate, FPS, audio info |
| `extract_frames` | Pull frames at regular intervals |
| `convert_video` | Convert between MP4, WebM, MOV, AVI, GIF, MKV |

---

## 💬 Example Usage

Once connected, just ask your AI:

> "Resize screenshot.png to 800px wide"

> "Convert all the PNGs in this folder to WebP"

> "Strip the EXIF data from photo.jpg for privacy"

> "Compress this image to under 500KB"

> "Extract a frame every 5 seconds from demo.mp4"

> "What are the dimensions of banner.png?"

> "Make a grayscale version of logo.png"

> "Create a 128x128 thumbnail of product-photo.jpg"

---

## 📦 Installation

### Using uvx (recommended — zero install)
```bash
uvx media-mcp-server
```

### Using pip
```bash
pip install media-mcp-server
```

### With video support
```bash
pip install media-mcp-server[video]
```

> **Note:** Video tools require `ffmpeg` to be installed on your system. 
> Install it from [ffmpeg.org](https://ffmpeg.org/download.html) or via your package manager:
> ```bash
> # macOS
> brew install ffmpeg
> 
> # Ubuntu/Debian
> sudo apt install ffmpeg
> 
> # Windows (with Chocolatey)
> choco install ffmpeg
> ```

---

## 🔧 Configuration

### Config file locations

<details>
<summary><b>Claude Desktop</b></summary>

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
  "mcpServers": {
    "media-mcp": {
      "command": "uvx",
      "args": ["media-mcp-server"]
    }
  }
}
```
</details>

<details>
<summary><b>Claude Code</b></summary>
```bash
claude mcp add media-mcp -- uvx media-mcp-server
```
</details>

<details>
<summary><b>Cursor</b></summary>

Settings → MCP Servers → Add:
```json
{
  "media-mcp": {
    "command": "uvx",
    "args": ["media-mcp-server"]
  }
}
```
</details>

<details>
<summary><b>VS Code</b></summary>

Add to `.vscode/mcp.json`:
```json
{
  "servers": {
    "media-mcp": {
      "command": "uvx",
      "args": ["media-mcp-server"]
    }
  }
}
```
</details>

---

## 🧪 Development
```bash
git clone https://github.com/Adityaaery20/media-mcp.git
cd media-mcp
pip install -e ".[dev]"
pytest
```

### Test with MCP Inspector
```bash
npx @modelcontextprotocol/inspector uvx media-mcp-server
```

---

## 📋 Supported Formats

**Images:** PNG, JPEG, WebP, GIF, BMP, TIFF, ICO, AVIF

**Videos:** MP4, WebM, MOV, AVI, GIF, MKV *(requires ffmpeg)*

---

## 🗺️ Roadmap

- [ ] Batch operations (process entire directories)
- [ ] Image watermarking
- [ ] PDF to image conversion
- [ ] OCR (text extraction from images)
- [ ] Audio extraction from video
- [ ] Image collage/montage creation
- [ ] Smart crop (content-aware)
- [ ] SVG rasterization

---

## 📄 License

MIT — do whatever you want with it.

---

## 🤝 Contributing

Contributions welcome! Please open an issue first to discuss what you'd like to add.

---

**Built with [FastMCP](https://gofastmcp.com) and [Pillow](https://pillow.readthedocs.io/)**