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" }
  ]
}

Field	Values	Default
aspect	16:9, 9:16, 1:1, 4:5 (or set width/height)	16:9
duration	seconds	5 (7 for globe, 1 + 3 per country for fly)
fps	frames per second	30
camera	push-in, zoom-in, globe (3D Earth dive), fly (country to country), static, or { "move", "fill", "from" }	push-in
basemap	satellite, bluemarble, sentinel, paper (old parchment map)	satellite
pov	auto (the country's own official borders), default, or a code like ind, chn, pak	auto
effects.grade	natural, muted, mono	natural
effects.vignette	0 to 1	0.45
effects.blur	0 to 1: soft-focus edges, like a camera lens	0
effects.grid	true or { "step", "color", "opacity" }: lat/long grid over the sea only	off
effects.borders	true: thin borders of neighbouring countries	on for paper and states
labelAnim	default label animation for every highlight	rise

Each highlight:

Field	Values	Default
country	name ("India") or ISO code ("IN", "IND")	country or region required
region	a state or province: "California", "Bavaria", "US-CA", "IN-MH"
style	solid (tinted fill), highlight (rest of the world goes grey), outline, flag (the country's flag over the terrain)	solid
color	any CSS colour or red, yellow, blue, ...	a distinct colour per country
label	text, or false for none	the country name
border	{ "color", "width", "glow" } or false	white, glowing
labelAnim	rise, type (typewriter), spread (letters close in), slide, pop	rise
labelSize	multiplier on the automatic label size, e.g. 0.7 or 1.3	1
labelFont	sans, serif, or any font name	sans (serif on paper)
capital	true for the capital (a state's own capital for region), or a city name like "Mumbai"	off
start	seconds when this country starts animating	staggered automatically

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.