mapcast

mapcast

Animated map videos for explainers, documentaries and Shorts, from one line of JSON. Highlight any country, state or province on real satellite imagery or an old paper map: tracing borders, flags, glow, labels, capitals, data colours, a 3D globe dive and camera flights between countries. Free, open source, and built for AI agents to drive.

Full-quality version: docs/showcase.mp4

npx mapcast quick India -o india.mp4

That is the whole setup. The first run downloads Chromium and map data once (both cached); videos also need ffmpeg.

Ask your AI for it

mapcast is made to be driven by AI tools: you describe the map, the agent writes the scene, mapcast renders it.

"Make a YouTube Short that spins the globe and lands on Brazil with its flag."

"Old parchment map of Turkey, zooming in, with Istanbul marked."

"Colour these countries by unemployment: Spain 11.4, Greece 9.8, Germany 3.4."

Claude Code (skill and MCP server in one install):

/plugin marketplace add 21prnv/mapcast

/plugin install mapcast@mapcast

Claude Desktop, Cursor, Windsurf, Codex or any MCP client: add this to the client's MCP config.

{

"mcpServers": { "mapcast": { "command": "npx", "args": ["-y", "mapcast", "mcp"] } } }

The server offers render_map (saves the video or image and returns a preview of the final frame, so the agent can check its work) and preview_map (one frame, to check a scene before rendering). Every option is described in the tool schema.

Agents that read `SKILL.md` skills: npx skills add 21prnv/mapcast. The skill is in skills/mapcast, with 27 worked request-to-scene examples.

What it can do

• Styles: colour tint that keeps the terrain visible, spotlight (rest of the world turns grey), outline, or the country's flag laid over its land.
• Basemaps: NASA Blue Marble and Sentinel-2 satellite imagery, or an old parchment map with engraved coasts.
• Cameras: slow push-in, zoom in from a wide view, dive from a spinning 3D globe, fly from country to country.
• Places: every country by name or ISO code, plus 4,500 states and provinces ("California", "IN-MH"), with capitals or any city marked.
• Data maps: colour countries by a number with a legend, with names and values on the map.
• Formats: MP4, GIF, PNG, JPG in 16:9, 9:16, 1:1 or 4:5.
• Disputed borders: drawn the way the highlighted country officially draws them, or a neutral view on request.

Command line

npx mapcast quick "United States" --style highlight --color yellow -o usa.png

npx mapcast quick France --style flag -o france.mp4 npx mapcast quick Brazil --camera globe -o brazil.mp4 # dive in from a spinning Earth npx mapcast quick India France Japan --camera fly -o tour.mp4 # fly from country to country npx mapcast quick Italy --basemap paper -o italy.mp4

npx mapcast render scene.json -o out.mp4 # any scene; .mp4, .gif, .png or .jpg npx mapcast render scene.json -o out.png --at 1.2 cat scene.json | npx mapcast render - -o out.gif npx mapcast schema # the scene format as JSON Schema npx mapcast mcp # MCP server on stdio

Every file in examples/ renders as-is.

Scene format

{

"aspect": "16:9", "duration": 5, "camera": "push-in", "highlights": [ { "country": "India", "style": "solid", "color": "#c8102e", "label": "INDIA" } ] }

Each highlight:

Data maps

Colour countries by a number, with a legend:

{

"data": { "title": "GDP 2024 (trillion US$)", "prefix": "$", "unit": "T", "scheme": "heat", "values": { "India": 3.9, "China": 18.7, "Japan": 4.1 } } }

scheme is one of reds, blues, greens, heat, purples, diverging, or a list of colours. Set "labels" to "name", "value" (the number with prefix/unit) or "both" to label each country, and min/max to fix the colour range. A highlight's label can have a second line: "INDIA\n1.4 BILLION".

How it works

A scene is resolved against Natural Earth borders, the imagery tiles the camera path needs are fetched and cached, and a headless Chromium draws each frame on a canvas (WebGL for the globe). Frames are piped to ffmpeg. A 5 second 1080p clip takes about 15 seconds on a laptop.

Credits and licence

MIT. Map data, imagery and font licences are in NOTICE.md. Satellite imagery needs a credit line wherever you publish; mapcast prints the exact line after every render.

Contributions are welcome: see CONTRIBUTING.md.