media-gen-mcp

A personal MCP server that gives OpenCode the ability to generate images and videos mid-conversation — invoked as a tool, not a separate app — using free-tier AI media providers.

Built for generating visual assets and video clips for my own websites, apps, and projects, without paying for API access.

Providers

Provider	Capabilities	Trust level	Status
Agnes AI	image, video	untrusted	active
Cloudflare Workers AI	image	untrusted	active
Hugging Face Inference API	image	untrusted	active
Google Gemini	image	trusted	unavailable — free-tier image generation quota is policy-set to 0 as of Aug 2026; requires a billed Google Cloud project. Implemented and ready — flip status: active in config.yaml once a working key exists

trust_level determines how a provider's responses are handled: untrusted providers are unofficial/self-parsed and go through full schema validation before anything else happens; trusted providers use an official SDK assumed to already validate its own response shape. See ARCHITECTURE.md for the full reasoning.

Providers can each have multiple named accounts (e.g. multiple API keys for the same provider) — selectable explicitly per call, no auto-rotation. Some accounts need more than one secret: Cloudflare requires an account ID alongside its API token (account_id_env in config.yaml).

Setup

This repo isn't published to a public remote yet, so <repository-url> is a placeholder — substitute the URL you actually clone from, don't copy it verbatim. The explicit media-gen-mcp target keeps the following cd correct: a bare git clone defaults to a directory named after the repository, so cd media-gen-mcp only holds if the repo happens to be named media-gen-mcp.

git clone <repository-url> media-gen-mcp
cd media-gen-mcp
python -m venv .venv
.venv/bin/pip install -e .

Create a .env file in the project root with whichever providers you plan to use:

AGNES_API_KEY=...
CLOUDFLARE_API_TOKEN=...
CLOUDFLARE_ACCOUNT_ID=...
HUGGING_FACE_API_TOKEN=...
GEMINI_API_KEY=...   # optional — provider is currently marked unavailable

config.yaml maps each of these to a named account per provider — see the file itself, or ARCHITECTURE.md's Config section, for the full schema (multiple accounts per provider, per-provider defaults, hardening limits).

Register with OpenCode

Add to ~/.config/opencode/opencode.json (global, so it's available from any project):

{
  "mcp": {
    "media-gen-mcp": {
      "type": "local",
      "command": [
        "/absolute/path/to/media-gen-mcp/.venv/bin/python",
        "/absolute/path/to/media-gen-mcp/server.py"
      ]
    }
  }
}

Both paths must be absolute. This is a global config spawned from whatever directory you happen to be working in when OpenCode starts — a relative path only happens to work if you're inside this repo, and silently breaks everywhere else.

Confirm it's connected:

opencode mcp list

Tools exposed

• generate_image(prompt, provider?, account?, project_dir?, output_path?, ...) — generates an image, returns the saved file path.
• generate_video(prompt, provider?, account?, project_dir?, output_path?, ...) — starts an async video job (Agnes only), returns a job_id to poll.
• check_video_job(job_id) — checks/advances a video job; downloads and saves the file once complete.
• list_providers() — reports configured providers, their status, capabilities, and accounts.

Where a file is saved follows this priority: an explicit output_path → under project_dir/ai-media/ if given → the configured default output directory otherwise.

Project docs

• ARCHITECTURE.md — the full design: provider abstraction, trust-level validation, async video job handling, accounts, config schema, and the current state of the system.
• progress-tracker.md — current build status, the task list, and the incidents/lessons that shaped the decisions above.
• AGENTS.md — standing conventions for AI coding agents working on this codebase (testing discipline, hard rules, definition of done).

License

Released to the public domain under The Unlicense — see UNLICENSE.md. Free to copy, modify, and distribute; provided without warranty.

Status

Personal v1, built for a single user. Secrets live in a repo-adjacent .env; not currently packaged for distribution to other users or other machines (see ARCHITECTURE.md's "Future: distribution" note for what that would need). Deterministic image editing (background removal, overlays, compositing) is explicitly out of scope — this project only generates media.