# video-probe-mcp

> Let any MCP client inspect local video and audio files with `ffprobe` before it ships them.

![demo](assets/demo.gif)

![license](https://img.shields.io/badge/license-MIT-black)

A narrow [Model Context Protocol](https://modelcontextprotocol.io) server. It wraps one system, `ffprobe`, and does one job: return structured media metadata from a local file.

```bash
codex mcp add video-probe-mcp -- npx -y github:omidsaffari/video-probe-mcp
```

## What it does

- Exposes one tool, `probe_media`, backed by `ffprobe`.
- Reads a local media file and returns JSON with format, duration, bitrate, file size, and stream metadata.
- Uses the bundled `ffprobe-static` binary by default, or `FFPROBE_PATH` when you want to point at a system install.

It does not transcode, edit, upload, call a model, or reach a remote API.

## Install

### Codex

```bash
codex mcp add video-probe-mcp -- npx -y github:omidsaffari/video-probe-mcp
```

### Claude Code and other MCP clients

Add to your MCP config (`.mcp.json` or the client's `mcpServers` block):

```json
{
  "mcpServers": {
    "video-probe-mcp": {
      "command": "npx",
      "args": ["-y", "github:omidsaffari/video-probe-mcp"]
    }
  }
}
```

### From source

```bash
git clone https://github.com/omidsaffari/video-probe-mcp
cd video-probe-mcp
npm install
npm run build
```

Then point your MCP client's command at:

```bash
node /absolute/path/to/video-probe-mcp/dist/index.js
```

## Configuration

No API key is needed. By default the server uses the bundled `ffprobe-static` binary. To use a specific local binary, set `FFPROBE_PATH`:

```json
{
  "mcpServers": {
    "video-probe-mcp": {
      "command": "npx",
      "args": ["-y", "github:omidsaffari/video-probe-mcp"],
      "env": {
        "FFPROBE_PATH": "/opt/homebrew/bin/ffprobe"
      }
    }
  }
}
```

See [.env.example](.env.example) for local development.

## Tool

### `probe_media`

Input:

```json
{
  "filePath": "/absolute/path/to/video.mp4",
  "includeRawJson": false,
  "timeoutMs": 15000
}
```

Output is JSON text:

```json
{
  "format": {
    "name": "mov,mp4,m4a,3gp,3g2,mj2",
    "durationSeconds": 12.48,
    "bitRate": 3091210,
    "streamCount": 2
  },
  "streams": [
    {
      "type": "video",
      "codec": "h264",
      "width": 1920,
      "height": 1080,
      "frameRate": "30/1"
    }
  ]
}
```

Use absolute paths when possible. Relative paths resolve from the MCP server process cwd, which may differ by client.

## Why this exists

Agentic video workflows are growing fast, but agents still need a small deterministic check before they publish a render: "what file did I actually make?" Broad media servers mix generation, editing, conversion, and provider APIs. This server is just the inspect step.

## License

MIT - see [LICENSE](LICENSE). Built by [Omid Saffari](https://omidsaffari.com).