Spoofzy for Claude: MCP server and skill

Spoof images and videos with Spoofzy from Claude Code, Claude Desktop or any other Model Context Protocol client. Ask Claude for unique versions of your photos and clips, strip hidden metadata, or run your saved Spoofzy Cloud workflows. Results land next to your originals.

You:     Make 5 unique versions of every video in ~/Reels/drop-12, keep the captions readable.
Claude:  That's 4 videos × 5 versions with the minimal look, included in your plan. Results go to
         ~/Reels/drop-12/spoofzy-output. Go ahead?
You:     yes
Claude:  Done: 20 files saved in ~/Reels/drop-12/spoofzy-output (beach-spoofzy-01.mp4 … sunset-spoofzy-05.mp4).

• Spoof: make 1, 5, 10, 20, 30, 40 or 50 unique versions per file with the classic, subtle, stronger or minimal (text- and layout-preserving) look, plus optional mirror, 1080p/4K export, watermark and border.

• Clean metadata: remove GPS location, device details and capture dates from photos and videos.

• Workflows: run saved Spoofzy Cloud workflows (for example Caption → Spoof ×5) on local files or saved originals.

• One file, no dependencies: spoofzy_mcp.py needs only Python 3.9 or later.

1. Get a Spoofzy API key

Use either key, or both:

For a Cloud key, tick Read jobs and results and Upload and run processing. Add Read workflows and history and Run saved workflows to use workflows, and Read saved originals and voices to list your library.

Keep keys out of chats, prompts and repositories. The steps below store them outside the conversation.

Related MCP server: image-generator-mcp

2. Install

Claude Code (plugin: MCP server + skill)

In Claude Code:

/plugin marketplace add spoofzy/video-image-spoofer-mcp
/plugin install spoofzy@spoofzy

Or from a terminal:

claude plugin marketplace add spoofzy/video-image-spoofer-mcp

claude plugin install spoofzy@spoofzy

Then save your key (step 3) and restart Claude Code. The skill is available as /spoofzy:spoof, and Claude also uses it automatically when you ask to spoof media.

Claude Code (MCP server only)

curl -fsSLo ~/spoofzy_mcp.py https://raw.githubusercontent.com/spoofzy/video-image-spoofer-mcp/main/spoofzy_mcp.py

claude mcp add spoofzy --scope user --env SPOOFZY_WAIT_SECONDS=600 -- python3 ~/spoofzy_mcp.py

Claude Desktop

Download spoofzy-<version>.mcpb from Releases and open it. Claude Desktop asks for your key and stores it in the system keychain. Python 3.9+ must be installed. macOS includes it with the Xcode Command Line Tools.

Or add it by hand to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "spoofzy": {
      "command": "python3",
      "args": ["/absolute/path/to/spoofzy_mcp.py"]
    }
  }
}

Other MCP clients (Cursor, VS Code, Codex, Windsurf, …)

Any client that runs stdio servers works. With uv installed, no download is needed:

{
  "mcpServers": {
    "spoofzy": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/spoofzy/video-image-spoofer-mcp", "spoofzy-mcp"]
    }
  }
}

Without uv, use "command": "python3" and the path to spoofzy_mcp.py, as in the Claude Desktop example.

3. Save your key

Run setup once in a terminal. It asks for your key(s) without echoing them and saves them to ~/.config/spoofzy/credentials.json (%APPDATA%\spoofzy on Windows), readable only by you. Every install on the machine uses that file.

python3 ~/spoofzy_mcp.py setup

Plugin users can run setup from any copy of the script (the curl command above downloads one) or with uvx --from git+https://github.com/spoofzy/video-image-spoofer-mcp spoofzy-mcp setup. You can also set environment variables instead: SPOOFZY_CLOUD_API_KEY and/or SPOOFZY_API_KEY. Check everything with:

python3 ~/spoofzy_mcp.py doctor

Using it

Just ask:

• "Spoof ~/Desktop/post.jpg"

• "Make 10 versions of ~/Videos/clip.mov, mirrored, exported at 1080p"

• "Make 5 versions of everything in ~/Reels/new with the minimal look"

• "Remove the location and camera info from ~/Pictures/IMG_2041.HEIC"

• "Run my 'Caption + Spoof' workflow on ~/Videos/hook.mp4"

• "Is my Spoofzy run done yet?"

Claude checks your plan with spoofzy_account, confirms what will run and what it costs, then saves the results as <name>-spoofzy-01.<ext>, -02, … in a spoofzy-output folder next to each file. Existing files are never overwritten. Long videos keep processing after Claude's call returns and are saved automatically when ready, or on request with spoofzy_get_run.

Tools

Option details and per-plan limits: skills/spoof/reference.md.

Command line

The same file is a small CLI:

python3 spoofzy_mcp.py spoof ~/Videos/clip.mp4 --versions 5 --look minimal

python3 spoofzy_mcp.py clean ~/Pictures/*.jpg --keep-dates

python3 spoofzy_mcp.py status RUN_ID --download

Configuration

Privacy and safety

• Reads only what you name. Only the image and video files (or folders) passed to a tool are read. Each file's signature is checked, so text files, keys, documents and other non-media files cannot be uploaded even if named.

• Talks only to Spoofzy. Files go to your own Spoofzy account over HTTPS. API keys go only to the Spoofzy API, never to storage links. Redirects are not followed for API calls, and plain-HTTP links are refused.

• Writes only results. Files are saved only in the output folder and never overwrite an existing file.

• No telemetry. The server collects nothing. Spoofzy processes your files under its Terms and Privacy Policy and keeps results for a limited time.

• Spending is explicit. Runs use your plan's allowance. The skill has Claude confirm files, versions and cost first, and request_id makes retries safe from double charges.

Only process media you own or are authorized to use. Spoofzy does not guarantee how any platform treats an upload.

Found a security issue? See SECURITY.md.

Troubleshooting

How it works

spoofzy_mcp.py is a single-file stdio MCP server. It supports both the stateless 2026-07-28 protocol revision (server/discover, per-request _meta) and the initialize-based 2024-11-05 to 2025-11-25 revisions. It talks to:

• the Spoofzy Cloud Developer API at https://cloud.spoofzy.com/developer/v1: capabilities, uploads, jobs, chains, automations, masters

• the prepaid Spoofer API at https://api.spoofzy.com/api/v1: spoofer/account, spoofer/uploads, spoofer/jobs, spoofer/batches (OpenAPI)

Each file is uploaded once to a short-lived signed storage link. A job, many-version job, Studio run, workflow run or prepaid batch is then started with a stable idempotency key. The server polls within Spoofzy's rate limit (45 requests per minute per account) and downloads the results.

Development

python3 -m unittest discover -s tests -v

python3 scripts/build_mcpb.py

The tests drive the real server over stdio against an in-process fake of both Spoofzy APIs (tests/fake_spoofzy.py), with no network or account needed. The build script writes the Claude Desktop bundle to dist/. Bump the version in spoofzy_mcp.py, manifest.json, pyproject.toml and both .claude-plugin files together. The build script checks they match.

Repository layout:

spoofzy_mcp.py                 MCP server + CLI (the whole runtime)
skills/spoof/                  Claude skill: SKILL.md and reference.md
.claude-plugin/                Claude Code plugin (with its MCP server config) + marketplace
manifest.json, assets/         Claude Desktop extension (MCPB)
scripts/build_mcpb.py          Builds dist/spoofzy-<version>.mcpb
tests/                         Unit and end-to-end tests

License

MIT. The license covers the code, not the Spoofzy name or logo.