postward-creative-mcp
OfficialIt exposes MCP tools that let your AI assistant edit, generate, inspect, and prepare media files locally or via optional AI providers.
Edit videos with ffmpeg: trim, concat, transcode to 9:16/1:1/16:9, extract frames/audio, create GIFs, add watermarks, burn subtitles, overlay text, fades, speed changes, reverse, flip, crop, adjust/replace audio.
Edit images with ImageMagick: resize, convert between PNG/JPEG/WebP, create thumbnails, read image info.
Inspect files: probe media details (duration, resolution, codecs), compute SHA-256 checksums, list all available tools.
Generate media with AI providers (when keys are configured): images, voiceovers, music, short videos, image animation, image editing, background removal/replacement, and upscaling.
Manage AI provider keys locally: store keys via
set_provider_keyand check masked status withget_provider_status.Optional Postward handoff:
prepare_for_postwardformats local file metadata for a later Postward upload flow — no upload itself.Everything is local-first: local files, no watermark, no account required; outputs return file path, MIME type, byte size, and SHA-256.
Enables text-to-speech voiceover generation using ElevenLabs.
Provides local video editing with FFmpeg, including trimming, concatenating, transcoding, frame and audio extraction, GIF creation, watermarking, subtitles, fades, speed changes, reversing, flipping, cropping, volume adjustment, audio replacement, and text overlays.
Enables AI image generation with DALL-E 3 and text-to-speech voiceover generation through OpenAI.
Enables AI background removal and image upscaling via Replicate.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@postward-creative-mcp Create a 15-second vertical video for my coffee shop with a calm voiceover and background music."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
postward-creative-mcp
Video and image editing on your own machine, driven by the AI assistant you already use. ffmpeg and ImageMagick under natural language — with zero network calls: no API keys, no account, no watermark, no telemetry, no uploads. Ever.
postward-creative-mcp is a local MCP server (Model Context Protocol —
the standard way AI assistants like Claude, ChatGPT, Cursor or Codex talk
to external tools). Once connected, your AI assistant can trim, merge,
crop, caption, speed up, reverse, watermark and convert your videos and
images — by simply asking for it in plain language.
You: "Cut the first 15 seconds, add my logo bottom-right and burn these subtitles."
AI: → trim_video + add_watermark + burn_subtitles (ffmpeg, 100% local)
→ "Done: /tmp/postward-creative/launch-final.mp4"Need AI generation (images, video, voiceovers)? That is Postward's hosted Creative — see How it fits with Postward.
Two products, one ecosystem
Postward ships two MCP servers with different jobs:
postward-creative-mcp (this repo) | Postward MCP (postward.cc) | |
What it does | Edits media on your machine (ffmpeg/ImageMagick) | Generates media (hosted AI with your keys) plus storage, review, scheduling and publishing |
Runs on | Your computer (Docker) | Postward's servers |
Network calls | None — 100% offline | Only to your AI providers, from Postward's servers |
API keys | None needed | Yours, sealed server-side |
Output | Local files + metadata | Workspace assets in Postward storage |
Cost | Free, open source, no account | Paid plans with credit metering |
Publishing | ❌ never | ✅ via review + approval |
Account required | ❌ never | ✅ |
This server never publishes, never uploads, and never talks to
Postward — it doesn't even go online. It is a complete standalone
product. If you later want AI generation, durable asset storage, team
review, approval flows, scheduling or social publishing, the
Postward MCP picks up exactly where this tool
ends — one of its tools (prepare_for_postward) even formats your
file's metadata for that handoff. But that's optional, and nothing in
this repo nags you about it.
Related MCP server: Modisign MCP
Installation
The only dependency is Docker. The image ships ffmpeg, ImageMagick and
fonts — nothing to install on your machine, no Node.js, no keys, no accounts.
Generated files persist through the named volume (postward-creative-output)
shown below; you can also bind-mount any local folder instead.
Step 0 — install Docker (once)
If you don't have it yet:
Windows / macOS: install Docker Desktop (free for personal use) and start it once — it must be running for your assistant to reach the tools.
Linux: install Docker Engine —
curl -fsSL https://get.docker.com | sh— and add yourself to the docker group so you can run it without sudo:sudo usermod -aG docker $USER(log out and back in).
Check it works:
docker --versionIf that prints a version, you're ready. Without Docker running, the server cannot start and no tools appear in your assistant — that is expected; there is no fallback (this is what keeps your machine clean and your files local).
Step 1 — connect the server to your assistant
Option A — one command (Claude Code)
claude mcp add postward-creative -- docker run -i --rm -v postward-creative-output:/tmp/postward-creative ghcr.io/postward-cc/creative-mcp:latestFor Codex CLI, add the same server to ~/.codex/config.toml:
[mcp_servers.postward-creative]
command = "docker"
args = ["run", "-i", "--rm", "-v", "postward-creative-output:/tmp/postward-creative", "ghcr.io/postward-cc/creative-mcp:latest"]Option B — config file (Claude Desktop, Cursor, anything that speaks MCP)
Add to claude_desktop_config.json or .cursor/mcp.json and restart the app:
{
"mcpServers": {
"postward-creative": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "postward-creative-output:/tmp/postward-creative",
"ghcr.io/postward-cc/creative-mcp:latest"
]
}
}
}Restart your AI assistant. That's it — ask it "what tools do you have for video editing?" and it will discover this server. There is nothing to configure after that — no keys, no accounts.
Prefer to avoid Docker? It's possible to run the bundle directly with Node.js 22+, but then you must provide ffmpeg, ffprobe, ImageMagick and fonts on your PATH — that's why Docker is the supported path. See Development if you want to go this route.
Your first edit
With the server connected and your assistant restarted, just talk to it.
Grab any video (say, ~/Videos/demo.mp4) and try:
Trim ~/Videos/demo.mp4 to the first 20 seconds, add the text
"MY LAUNCH" in white at the bottom, and burn subtitles from
~/Videos/legendas.srtYour assistant will chain trim_video → overlay_text → burn_subtitles
and answer with something like:
{
"filePath": "/tmp/postward-creative/7f3a….mp4",
"mimeType": "video/mp4",
"bytes": 2411724,
"sha256": "9f86d081884c7d65…"
}Two things to know:
Where the files are. Outputs live inside the container's
/tmp/postward-creative, which the named volume keeps across restarts. Want them in a normal folder? Bind-mount one in the config instead —"postward-creative-output:/tmp/postward-creative"becomes"/Users/you/Videos/out:/tmp/postward-creative"— and every result lands in that folder directly.Errors are loud. If something can't be done (wrong path, invalid parameter, unsupported aspect), the tool fails with a machine-readable error your assistant can read and correct — it never silently produces the wrong video.
More one-liners to try: "make a 3-second GIF from clip.mp4 starting at 0:05"
(create_gif), "normalize this to vertical 9:16" (transcode_video),
"what's in this file?" (probe_media), "join these two clips"
(concat_videos).
What your assistant can do
Video editing (ffmpeg — 16 tools, free, 100% local)
trim_video, concat_videos, transcode_video (9:16 / 1:1 / 16:9),
extract_frame, extract_audio, create_gif, add_watermark,
burn_subtitles, add_fade, change_speed, reverse_video, flip_video,
crop_video, adjust_volume, replace_audio, overlay_text
Image tools (ImageMagick — 4 tools, free, 100% local)
resize_image, convert_format (PNG ↔ JPEG ↔ WebP), image_thumbnail,
image_info
Utilities
Tool | What it does |
| Duration, resolution, codecs, bitrate of any media file |
| SHA-256 of any file |
| Everything this server offers, in one list |
The optional Postward bridge
Tool | What it does |
| Formats a local file's metadata (path, MIME, bytes, SHA-256) for Postward's upload flow. No upload, no auth — just the handoff info. |
Every result is portable
Every edit returns:
{
"filePath": "/tmp/postward-creative/a1b2….mp4",
"mimeType": "video/mp4",
"bytes": 1048576,
"sha256": "9f86d081884c7d65…"
}The file is yours — a plain local file with a checksum and its MIME type. No account needed to open it, no watermark on it, no strings attached.
Non-negotiable principles
The server makes zero network calls. Not "telemetry-free": the editing tools cannot phone home. The only network touch in the whole project is the launcher's explicit update check at container start.
No API keys, no account — editing is local compute, forever free.
No watermark on any output — ever.
No uploads — your media never leaves your machine through this server.
No feature gating behind Postward signup — every tool works standalone.
No silent fallbacks — errors carry machine codes and sanitized messages; wrong inputs fail loudly instead of degrading.
How it differs from hosted AI tools
Your machine, your files. Media never sits on someone else's server — this server has no network stack usage at all.
Standard MCP. Works with any MCP-capable assistant — Claude Desktop, ChatGPT desktop, Cursor, Codex CLI, and anything else that speaks MCP.
Open source, MIT licensed. Audit it, fork it, self-host it.
How it fits with Postward
The moment content needs to leave your laptop — AI generation, scheduling
to multiple social accounts, a teammate reviewing before anything goes
out, an approval trail for clients, one library of every asset — that's
Postward. This tool edits locally; Postward
generates, governs and publishes. The handoff is one step
(prepare_for_postward), and it's optional forever.
Development
git clone https://github.com/postward-cc/postward-creative-mcp
cd postward-creative-mcp
npm install
npm run typecheck # strict TypeScript
npm test # unit suite (arg builders, contracts, server surface)
npm run build # typecheck + esbuild bundle → dist/index.cjs
node scripts/e2e.mjs # e2e: drives the bundled server through every toolThe e2e harness spawns the real server, calls all 23 tools on generated
fixtures plus a multi-tool pipeline (trim → caption → brand → fade → speed →
checksum → handoff), and asserts on the actual output files. CI runs it
inside the Docker image (.github/workflows/e2e.yml), so the artifact
users pull is exactly what gets exercised — on GitHub-hosted runners, with
layer cache.
On top of that, .github/workflows/client-smoke.yml (manual dispatch +
weekly schedule) runs a real third-party MCP client: it installs
oh-my-pi in a container, registers
the bundled server via project .mcp.json, and has the omp agent execute
all 23 tools, asserting a 24/24 PASS report. Needs an OMP_MODEL_API_KEY
secret (an LLM key with credits); without it the job self-skips.
The same flow works locally: point a project .mcp.json at the server and
run any MCP client — omp -p, Claude Desktop, Cursor, mcode, …
Stack: TypeScript, Node.js 22+, official MCP SDK, esbuild.
Releases: pushing a
v*tag publishes the Docker image toghcr.io/postward-cc/creative-mcp, the bare media base image toghcr.io/postward-cc/creative-mcp-media, and the package to npm (@postward-cc/creative-mcp).
The media base image
ghcr.io/postward-cc/creative-mcp-media:<release tag> carries the toolchain and
nothing else — ffmpeg, ImageMagick, DejaVu fonts, CA certificates on
node:24-bookworm-slim. No workdir, no entrypoint, no volume.
Use it when you need the same media tooling but not this MCP server:
FROM ghcr.io/postward-cc/creative-mcp-media:v0.7.0
# ... your own layersPin the release tag. The tag freezes this repository's whole state, toolchain
included, so v0.7.0 keeps giving you exactly that toolchain as later releases
move on.
The package's own runtime is built FROM this same stage, so a server image and
a consumer image cannot drift apart on the apt line — which is the failure this
stage exists to remove.
Image names
The npm package is the root and the images follow it, with a -media suffix
marking the bare toolchain:
Artifact | Name |
MCP server image |
|
Media base image |
|
npm package |
|
The package is the one that cannot move: an npm scope is permanent, so renaming means deprecating and publishing a new name. The images followed it rather than the other way round.
Releases up to and including v0.4.0 published the server image as
postward-creative-mcp. That path is gone; creative-mcp is the name to use.
The pure FFmpeg argument primitives are also exported as a typed package subpath for other Postward tools to share:
import {
atempoChain,
concatListContent,
escapeFilterValue,
parseTimestamp,
} from "@postward-cc/creative-mcp/ffmpeg-args"This subpath has no filesystem or process effects: callers provide paths,
consume argument/filter strings, and keep their own I/O, validation policy and
error presentation. The Creative MCP adapts shared input errors to
CreativeError; other consumers can adapt them to their own domain.
License
MIT — © Postward
Updating
Already handled: every start, the launcher checks ghcr for a newer image, pulls it when one exists, and falls back to the cached image when offline. New releases reach you on the next assistant restart, with zero action.
Manual option (or to refresh while offline-then-online without restarting):
scripts/update.shTo know which version a session is running: ask your assistant — the server
reports its version in the MCP handshake. (Windows users with the plain
docker run config: docker pull <image> + restart.)
Available Tools
35 toolsadd_fadeA
Add a fade-in and/or fade-out to a video (seconds).
Inputs: video_path (required), fade_in, fade_out.
add_watermarkC
Overlay a logo image (PNG with transparency works best) on top of a video.
Inputs: logo_path (required), video_path (required), position.
adjust_volumeA
Adjust audio volume, in decibels (+6 = louder, -6 = quieter).
Inputs: gain (required), video_path (required).
animate_imageA
Animate a static image using AI image-to-video (fal). The source image is a local file path. Requires a fal API key. Returns the path to the generated MP4.
Inputs: prompt (required), image_path (required), model, duration.
burn_subtitlesA
Burn an .srt subtitle file into the video pixels (visible on every platform). Optional ASS force_style string, e.g. "FontSize=24,PrimaryColour=&H00FFFFFF".
Inputs: srt_path (required), video_path (required), style.
change_speedA
Change playback speed (0.25x to 4x). Video and audio stay in sync.
Inputs: rate (required), video_path (required).
checksum_fileA
Calculate the SHA-256 hash of any local file.
Inputs: file_path (required).
concat_videosA
Join 2 to 4 video clips into one. Clips must share the same codec/resolution (stream copy, no re-encode) — use transcode_video first if they differ.
Inputs: videos (required).
convert_formatA
Convert an image between PNG, JPEG and WebP. JPEG gets a white background where the source is transparent.
Inputs: format (required), image_path (required).
create_gifB
Create a looping animated GIF from a segment of a video.
Inputs: video_path (required), start, width, duration.
crop_videoC
Cut a video to a rectangular region. Width/height must be even numbers.
Inputs: x (required), y (required), width (required), height (required), +1 more.
edit_imageA
Edit an existing image using a text instruction (e.g. "make the background blue", "add a red hat"). Uses fal or OpenAI. Requires the matching provider key. Returns the path to the edited image.
Inputs: prompt (required), image_path (required), model, provider.
extract_audioC
Pull the audio track out of a video as an AAC .m4a file.
Inputs: video_path (required).
extract_frameA
Grab a single frame from a video as a PNG image, at a timestamp ("90", "1:30", "00:01:30").
Inputs: timestamp (required), video_path (required).
flip_videoB
Mirror a video horizontally or vertically.
Inputs: direction (required), video_path (required).
generate_imageA
Generate an image from a text description using AI (fal FLUX, OpenAI DALL-E 3 or Stability). Requires a provider API key (set_provider_key). The image is saved locally — it is not uploaded anywhere. For Stability, any WxH size is mapped to the nearest supported aspect ratio.
Inputs: prompt (required), size, model, provider.
generate_musicA
Generate instrumental background music from a description (fal). Requires a fal API key. Returns the path to the generated audio file.
Inputs: prompt (required), model, duration.
generate_videoA
Generate a short video from a text description using AI (fal or Runway). Requires a provider API key. Generation is slow (minutes). Returns the path to the generated MP4.
Inputs: prompt (required), model, duration, provider.
generate_voiceoverA
Generate a voiceover from text using AI text-to-speech (fal, OpenAI TTS or ElevenLabs). Requires a provider API key. Returns the path to the generated MP3.
Inputs: text (required), model, speed, voice, +1 more.
get_provider_statusA
Check which AI provider API keys are configured (keys are only shown masked). Also lists which providers each generation tool can use.
Inputs: no named parameters.
image_infoB
Get an image's dimensions, format, byte size, MIME type and SHA-256.
Inputs: image_path (required).
image_thumbnailB
Create a small preview version of an image (aspect ratio preserved).
Inputs: image_path (required), size.
list_toolsA
List every tool this server offers, with a one-line description. Useful to plan multi-step content work.
Inputs: no named parameters.
overlay_textB
Burn a text caption onto the video (e.g. a hook or a call to action). Text is centered by default.
Inputs: text (required), video_path (required), color, fontSize, +1 more.
prepare_for_postwardA
Format a local file's metadata for upload to Postward (postward.cc). Returns the file info (path, MIME type, byte size, SHA-256) that you need to call request_source_asset_upload and then register_source_asset in the Postward MCP. This tool does NOT upload or authenticate — it only prepares the metadata. Use it when the user asks to move content into Postward for storage, review, scheduling or publishing.
Inputs: file_path (required), name.
probe_mediaA
Get detailed info about a local media file — duration, resolution, codecs, bitrate. Works on video, audio and images.
Inputs: file_path (required).
remove_backgroundA
Remove the background from an image, producing a transparent PNG (Replicate or fal). Requires the matching provider key.
Inputs: image_path (required), model, provider.
replace_audioA
Swap a video's audio track with another audio file. Output ends when the shortest input ends.
Inputs: audio_path (required), video_path (required).
replace_backgroundA
Replace the background of an image following a text description (fal). Requires a fal API key. Returns the path to the new image.
Inputs: prompt (required), image_path (required), model.
resize_imageC
Scale an image to fit within width x height (aspect ratio preserved).
Inputs: width (required), height (required), image_path (required).
reverse_videoA
Play a video backwards (audio included when present).
Inputs: video_path (required).
set_provider_keyA
Configure an AI provider API key. Keys are stored locally in ~/.postward-creative/keys.json (file permission 0600) and never leave this machine — they are sent only to the provider they belong to.
Inputs: key (required), provider (required).
transcode_videoA
Normalize a video to a fixed aspect ratio (9:16, 1:1 or 16:9) with padding, re-encoded. Unknown aspect values are rejected — nothing silently falls back.
Inputs: aspect (required), video_path (required), quality.
trim_videoA
Cut a segment out of a video (start to end). Timestamps accept seconds ("90"), "MM:SS" or "HH:MM:SS". Cut points snap to the nearest keyframe (stream copy, no re-encode).
Inputs: end (required), start (required), video_path (required).
upscale_imageB
Upscale an image to higher resolution — 2x or 4x (Replicate Real-ESRGAN or fal). Requires the matching provider key.
Inputs: image_path (required), model, scale, provider.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 35 tools
Each tool targets a distinct media operation or generation task, and the descriptions clarify inputs and outputs. A few pairs could be confused without careful reading—resize_image vs upscale_image, probe_media vs image_info, animate_image vs generate_video—but the boundaries are mostly clear.
The overwhelming pattern is snake_case verb_noun: generate_image, trim_video, crop_video, adjust_volume, set_provider_key. Only image_thumbnail and image_info break the pattern as noun_noun names, and list_tools is a minor meta exception.
35 tools is a heavy surface for a single MCP, well beyond the comfortable 3-15 range and even above the 16-25 heavy band. The broad video/image/AI scope explains some of the size, but the set would be easier to navigate if split into smaller focused servers or curated down.
The server covers a wide range of key creative workflows: AI generation, image transformations, video editing, audio replacement, metadata inspection, and Postward preparation. Minor gaps exist, such as no direct caption generation from audio and no slideshow-from-images tool, but most multi-step workflows can be assembled from the existing tools.
Related MCP Connectors
Generate reproducible image, video, and audio assets with leading models and your own provider keys.
Transform video, audio and images, and generate media from prompts. FFmpeg, captions, models.
Image and video AI tools and your own pipelines, run from any AI assistant.
Generate, extend and edit AI images and videos, then assemble clips on a timeline and render.
Related MCP Servers
- AlicenseCqualityBmaintenanceOpen-source local-first AI media workbench with Canvas, video editor, Assets, and MCP control.38367Apache 2.0
- AlicenseAqualityCmaintenanceEnables AI assistants to generate animated overlays and edit short videos — cutting clips together, removing pauses, adding captions, and exporting overlays as MP4, MOV or WebM with transparent or green-screen backgrounds. All rendering, transcription and media handling happen locally on the user's own computer.11461 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to edit video locally through FFmpeg: probing media, validating and previewing JSON edit projects, rendering short-form clips with captions, reframing, transitions and ducked music. Also analyses existing videos and applies or saves reusable format templates, without cloud services or API keys.1Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables local-first video editing for creators and AI agents through tools for auto-editing, shorts, captions, music, QC, transcription, reframing, rendering, and project handoff while footage stays on the user's machine.318 npm4MIT