# Image Forensics MCP Server

An MCP (Model Context Protocol) server that gives AI assistants forensic analysis capabilities to help detect AI-generated images. Uses noise maps, Error Level Analysis, FFT frequency analysis, spectral decay analysis, color channel analysis, and metadata inspection.

## Install

One command — requires [uv](https://docs.astral.sh/uv/getting-started/installation/):

```bash
claude mcp add -s user image-forensics -- uvx --from git+https://github.com/surewht/image-forensics-mcp image-forensics-mcp
```

That's it. Restart Claude Code and the tools are available.

### Alternative: install from local clone

```bash
git clone https://github.com/surewht/image-forensics-mcp.git
cd image-forensics-mcp
claude mcp add -s user image-forensics -- uvx --from . image-forensics-mcp
```

### Manual config

Add to `~/.claude.json`:

```json
{
  "mcpServers": {
    "image-forensics": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/surewht/image-forensics-mcp", "image-forensics-mcp"]
    }
  }
}
```

## Tools

| Tool | What it does |
|------|-------------|
| `noise_map` | Extracts the noise pattern by subtracting a blurred version. AI images have unnaturally uniform noise. Returns visualization + statistics. |
| `error_level_analysis` | Multi-scale ELA — resaves at multiple JPEG qualities and analyzes error patterns. Detects splicing and compression inconsistencies. |
| `frequency_analysis` | 2D FFT spectrum analysis. Detects GAN grid artifacts and unusual frequency distributions. |
| `spectral_decay_analysis` | Power spectral density curve fitting (1/f^β). Based on CVPR 2025 research. Natural images follow characteristic decay; AI images may deviate. |
| `color_analysis` | RGB channel correlation, gradient correlation, entropy, and saturation analysis. Based on CVPR 2025 "Secret Lies in Color" research. |
| `metadata_check` | EXIF/metadata inspection for AI tool signatures (Stable Diffusion, DALL-E, Midjourney, etc.) + AI resolution fingerprinting. |
| `full_forensic_report` | Runs all 6 analyses, saves visualizations to `/tmp/image-forensics/`, returns a categorized verdict. |

## Usage

In Claude Code, just ask:

```
Analyze this image for AI generation: /path/to/image.jpg
```

Or use individual tools:

```
Run a noise map analysis on /path/to/image.png
Check the metadata of /path/to/image.webp
```

## How the verdict works

The `full_forensic_report` categorizes findings into three tiers:

| Tier | What triggers it | Example |
|------|-----------------|---------|
| **Definitive** | AI tool signatures in metadata (SD parameters, generation prompts) | Stable Diffusion PNG with `parameters` chunk |
| **Strong** | Forensic anomalies rarely seen in real photos (uniform noise, GAN artifacts, spectral anomalies, extreme saturation) | GAN periodic patterns in FFT spectrum |
| **Weak/Ambiguous** | Indicators also caused by social media processing (no EXIF, AI-typical resolution, uniform ELA) | Facebook-resized 768x768 JPEG with stripped metadata |

### Verdict scale

- **AI-GENERATED** — Definitive metadata proof found
- **LIKELY AI-GENERATED** — 3+ strong forensic anomalies
- **POSSIBLY AI-GENERATED** — 1-2 strong anomalies
- **INCONCLUSIVE** — Only weak/ambiguous indicators
- **LIKELY AUTHENTIC** — Minimal indicators, consistent with normal processing
- **NO INDICATORS** — Clean across all analyses

## Limitations

Modern AI generators (Flux, DALL-E 3, Midjourney v6+) produce images that are nearly indistinguishable from real photos at the pixel level. This tool works best when:

- **Metadata is intact** — SD parameters, generation prompts = definitive proof
- **Images show GAN artifacts** — periodic patterns in FFT = strong signal
- **Images haven't been re-compressed** — social media platforms strip metadata and resize to AI-typical dimensions, creating ambiguity

For ambiguous cases, visual inspection (teeth, hands, text, reflections, lighting inconsistencies) combined with these forensic tools gives the best results.

## Requirements

- Python >= 3.10
- [uv](https://docs.astral.sh/uv/) (for `uvx` install method)

Dependencies (installed automatically): `mcp[cli]`, `Pillow`, `numpy`, `scipy`

## License

MIT