# ๐ฌ UploadCheck MCP
### The quality gate between your AI and "publish".
**Your agent can generate video. It can't tell you the audio cut out at 0:08, a frame froze at the stitch seam, or the captions are cropped. UploadCheck can โ and hands back the exact timestamps to fix.**
[](https://www.npmjs.com/package/@drantoniou/uploadcheck-mcp)
[](./LICENSE)
[](#install)
[](https://uploadcheck.app)
> **For anyone whose agent, pipeline, or editor produces media that ships to real people** โ AI-video pipelines, Shorts/Reels, podcasts, client deliverables.
---
## The problem
An agent that writes code can run the tests. An agent that renders a video has no idea whether it's broken.
So the broken export ships: silence where narration should be, a frozen frame where two clips were stitched, lips out of sync, captions clipped by the platform UI, loudness well off target. Somebody notices in the comments.
**UploadCheck is the check your agent calls before it publishes.** Point it at the finished file. It returns `PASS`, `WATCH`, or `BLOCK` with per-flag timestamps and machine-actionable fixes โ so the agent repairs only the flagged span and re-checks, instead of guessing or shipping.
## Install
```bash
npx -y @drantoniou/uploadcheck-mcp
```
Claude Code
```bash
claude mcp add --env UPLOADCHECK_API_BASE_URL=https://api.uploadcheck.app \
--env UPLOADCHECK_API_KEY=YOUR_KEY \
--transport stdio --scope user uploadcheck -- npx -y @drantoniou/uploadcheck-mcp
```
Cursor / Claude Desktop (mcp.json)
```json
{
"mcpServers": {
"uploadcheck": {
"command": "npx",
"args": ["-y", "@drantoniou/uploadcheck-mcp"],
"env": {
"UPLOADCHECK_API_BASE_URL": "https://api.uploadcheck.app",
"UPLOADCHECK_API_KEY": "YOUR_KEY"
}
}
}
}
```
Codex
```bash
codex mcp add uploadcheck \
--env UPLOADCHECK_API_BASE_URL=https://api.uploadcheck.app \
--env UPLOADCHECK_API_KEY=YOUR_KEY \
-- npx -y @drantoniou/uploadcheck-mcp
```
Get a free key at **[uploadcheck.app](https://uploadcheck.app)** โ 40+ gates, 200 checked minutes/month, no card.
Machine-readable install snippets for every client live in [`mcp-install.json`](./mcp-install.json).
> **Keep your key private.** It's a secret bearer token tied to your plan minutes. Put it in your personal MCP config โ never in a committed file, a shared prompt, or a report.
## Use it
Once installed, just ask:
```text
check ./final-cut.mp4 before I upload
```
The agent calls `qc_run_local_file`, polls `qc_get_job`, then reads `qc_get_report` and shows you the flags with timestamps.
## What it checks
**40+ automated gates run on every check**, including:
| | |
|---|---|
| **Picture** | frozen/looped frames, black frames, canvas fit & pillarboxing, temporal warping, flicker, interlace combing |
| **Audio** | dead air, clipping, loudness (LUFS) & true peak, loudness range, channel balance, mains hum, dropouts |
| **Sync & text** | lip/audio drift, caption safe-area, text contrast, cropped or overlapping text |
| **Delivery** | resolution/codec/frame-rate spec, Shorts/Reels format |
Paid plans add AI "oracle" gates โ garbled speech, duplicated faces in AI crowds, narration match.
*What it doesn't do: it doesn't tell you whether a clip was AI-generated. It assumes it might be, and checks whether it's clean enough to publish.*
## Tools
| Tool | What it does |
|---|---|
| `qc_estimate_cost` | Estimate checked minutes and effective gates before running |
| `qc_run_local_file` | Check a local export (reads the file, sends it to the hosted API) |
| `qc_run_video` | Check a YouTube URL, signed URL, upload id, or base64 payload |
| `qc_get_job` | Poll status, progress, verdict, metered minutes |
| `qc_get_report` | The finished report: verdict + timestamped flags + evidence |
| `qc_get_events` | Lifecycle events, so the agent can explain what ran |
| `qc_get_artifacts` | List generated report artifacts |
| `qc_get_marker_csv` | Editor marker CSV (drop flags straight into your NLE timeline) |
| `qc_create_upload_url` | Signed upload URL for larger files |
Pass `idempotency_key` to `qc_run_video` when an agent might retry the same asset โ the API returns the existing job instead of duplicating the run.
Use `profile` when you know the media type but don't want to hand-pick gates: `auto`, `shorts`, `audio`, `thumbnail`, `generic_creator_video`, and named delivery targets like `youtube_shorts`, `podcast_delivery`, `broadcast_r128`, `ai_render_gate`. Explicit `checks` always win.
## Environment
```bash
export UPLOADCHECK_API_BASE_URL="https://api.uploadcheck.app"
export UPLOADCHECK_API_KEY=""
```
This package is a thin MCP client over the hosted UploadCheck API โ checks run server-side, not on your machine. Small and medium local files can be sent inline (base64) without durable storage; use signed upload URLs for large ones.
## Links
- **Website & free key** โ [uploadcheck.app](https://uploadcheck.app)
- **Docs (API + MCP + full gate reference)** โ [uploadcheck.app/docs](https://uploadcheck.app/docs/)
- **Signed PASS/BLOCK receipts** โ [uploadcheck.app/docs/receipts](https://uploadcheck.app/docs/receipts/)
## License
MIT โ see [LICENSE](./LICENSE).