Skip to main content
Glama

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 --version

If 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:latest

For 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.srt

Your 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

probe_media

Duration, resolution, codecs, bitrate of any media file

checksum_file

SHA-256 of any file

list_tools

Everything this server offers, in one list

The optional Postward bridge

Tool

What it does

prepare_for_postward

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

  1. 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.

  2. No API keys, no account — editing is local compute, forever free.

  3. No watermark on any output — ever.

  4. No uploads — your media never leaves your machine through this server.

  5. No feature gating behind Postward signup — every tool works standalone.

  6. 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 tool

The 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 to ghcr.io/postward-cc/creative-mcp, the bare media base image to ghcr.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 layers

Pin 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

ghcr.io/postward-cc/creative-mcp

Media base image

ghcr.io/postward-cc/creative-mcp-media

npm package

@postward-cc/creative-mcp

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.sh

To 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 tools
add_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

    B3.4/5.0

    Scored across 35 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      11
      461 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      1
      Apache 2.0