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.

[npm] [licence: MIT]

[mapcast showcase: globe dive into India, France flag, paper map of Italy, unemployment data map, flight to Turkey]

_{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

[Gallery: globe, India, France flag, paper Italy, data map, Turkey]

• 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.pngnpx mapcast quick France --style flag -o france.mp4npx mapcast quick Brazil --camera globe -o brazil.mp4          # dive in from a spinning Earthnpx mapcast quick India France Japan --camera fly -o tour.mp4   # fly from country to countrynpx mapcast quick Italy --basemap paper -o italy.mp4
npx mapcast render scene.json -o out.mp4        # any scene; .mp4, .gif, .png or .jpgnpx mapcast render scene.json -o out.png --at 1.2cat scene.json | npx mapcast render - -o out.gifnpx mapcast schema                              # the scene format as JSON Schemanpx 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.

[M8ven Score]