Media Gen

Media Gen MCP Server provides strict, type-safe multimodal tooling for generating and editing images, creating and managing video jobs, and fetching media from URLs or disk. It adheres to the MCP spec and exposes outputs in a flexible, client-friendly format suitable for a wide range of MCP-compatible clients and workflows.

How to use

You integrate Media Gen MCP Server with an MCP-compatible client by pointing the client at the MCP server entry point and invoking the available tools to generate images, edit images, create and manage videos, or fetch media. The server returns tool results using MCP content blocks, resource links, and structured content that your client can render or process. Use this to automate media pipelines, build multimodal assistants, or power media-enabled agents.

How to install

Prerequisites: Node.js LTS, npm, and a valid OpenAI API key if you plan to call OpenAI services.

Configuration and startup

Media Gen MCP Server is configured and started using an MCP client like fast-agent or Windsurf. The repository provides a ready-to-run PC-style setup that uses npx to fetch the server from GitHub.

Usage with an MCP client (stdin/stdout)

You can run the server via a standard MCP client configuration. The recommended approach is to use the following stdio configuration, which runs the server through npx and loads your environment variables from a file.

Security and access control

• Limit access to the output directories by restricting the user account running the server. - Use allowlists for remote fetches and strict path validation for local reads. - Store API keys outside the working directory and load them via an env file or secrets mechanism.

Troubleshooting

If you encounter issues, verify your OPENAI_API_KEY, ensure output directories are writable, and confirm that URLs and local paths are allowed by your environment configuration. Check the logs for detailed error messages and adjust your env file accordingly.

Notes and tips

The server automatically switches from inline base64 output to file/URL-based output when the combined base64 payload would exceed the configured MCP payload threshold. This helps avoid payload‑too‑large errors while preserving full image quality and accessibility via file paths or public URLs when configured.

Example start command

{
  "mcpServers": {
    "media_gen_mcp": {
      "command": "npx",
      "args": ["-y", "github:strato-space/media-gen-mcp", "--env-file", "/path/to/media-gen.env"]
    }
  }
}

Example environment variables

Set the following environment variables in your environment or in the env file loaded by the server: OPENAI_API_KEY, AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, OPENAI_API_VERSION. You may also set MEDIA_GEN_DIRS to define output locations and MEDIA_GEN_MCP_URL_PREFIXES to publish public URLs for generated media.

Project layout and tooling integration

The server exposes a suite of tools for images, videos, and documents, including openai-images-generate, openai-images-edit, openai-videos-create, openai-videos-remix, openai-videos-list, openai-videos-retrieve, openai-videos-delete, google-videos-generate, google-videos-retrieve-operation, google-videos-retrieve-content, fetch-images, fetch-videos, fetch-document, and test-images. Each tool adheres to strict MCP output formats and can be debugged via the test-images tool when you enable the test sample directory.

Developer notes

All tool handlers use strongly typed callbacks derived from Zod schemas, ensuring compile-time type safety and runtime validation. The server supports structured error handling, typed tool results, and backward-compatible output shapes when required by MCP clients.

Tool result and response format controls

Tools expose parameters like tool_result and response_format to control how results are delivered to MCP clients. For example, you can choose between resource_link (file/URL references) or embedded resource blocks for downloads, and you can select how structuredContent presents the data (urls, paths, or base64). These options enable flexible integration with diverse clients such as fast-agent, Windsurf, Claude Desktop, Cursor, and ChatGPT.

Security practices for file serving

When exposing media via public URLs, you should serve the output directory with a secure web server (for example nginx) and restrict access to the appropriate host. Use MEDIA_GEN_DIRS to point to the directory you intend to publish, and optionally configure MEDIA_GEN_MCP_URL_PREFIXES to generate public URLs.

References for tool usage

Access OpenAI and GenAI services by providing valid API keys and configuring model parameters as described in each tool's argument definitions. Use test-images to verify how different MCP clients handle various placements of content and structured content.

Versioning and maintenance

This server follows Semantic Versioning. Upgrade cautiously, test with vitest unit tests, and pin versions to ensure compatibility with your MCP client and OpenAI SDK versions.

Typed tool callbacks

All tool handlers use strongly typed callback parameters derived from Zod schemas. This provides static type safety, runtime validation, and MCP SDK compatibility for a robust development experience.

Tool annotations

Each tool includes hints indicating read-only behavior, idempotence, and whether it operates in an open-world context. These hints help MCP clients determine how to present tools to users.

Project structure

media-gen-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   │   └── lib/
│   │       ├── compression.ts    # Image compression (sharp)
│   │       ├── env.ts            # Env parsing + allowlists (+ glob support)
│   │       ├── helpers.ts        # URL/path validation, result building
│   │       ├── logger.ts         # Structured logging + truncation helpers
│   │       └── schemas.ts        # Zod schemas for all tools
│   └── test/                    # Unit tests
│       ├── ...

Meta and licensing

MIT license. This server is designed to work with the MCP ecosystem and aims to stay compatible with the latest MCP specifications and OpenAI APIs.

Available tools

openai-images-generate

Generates images from prompts using gpt-image-1.5 (and gpt-image-1 compatibility); supports background, size, quality, formats, and output formats.

openai-images-edit

Edits images with inpainting/outpainting; accepts single or up to 16 images and optional mask, with similar parameter surface to generate.

openai-videos-create

Creates video generation jobs via OpenAI Videos API; supports waiting for completion and asset downloads.

openai-videos-remix

Remixes an existing video job to create new results based on a prompt.

openai-videos-list

Lists video jobs with optional pagination and sorting.

openai-videos-retrieve

Retrieves a video job status by ID.

openai-videos-delete

Deletes a video job by ID.

openai-videos-retrieve-content

Downloads assets from a completed video job, returning a resource link or embedded resource.

google-videos-generate

Starts a Google GenAI Veo video generation operation and optionally downloads outputs.

google-videos-retrieve-operation

Polls an existing Google video operation for completion.

google-videos-retrieve-content

Downloads a completed Veo video asset as a resource link or embedded resource.

fetch-images

Fetches and processes images from URLs or local files with optional compression.

fetch-videos

Fetches videos from URLs or local files with optional downloads.

fetch-document

Fetches documents from URLs or local files and returns resource links or embedded resources.

test-images

Debug tool that returns sample images in the MCP result format for testing client handling.