Mapcast MCP Server

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.