mapcast

io.github.21prnvPublished by GitHub account 21prnvv0.1.1Updated Nov 3, 2026

Animated map videos from a prompt: globe dives, country highlights, flags, flights and data maps.

VerifiedSTDIODesktop onlyData & AnalyticsMedia & Design

Overview

AI-generated overview

Renders animated map videos and still images — country highlights, flags, globe dives, flights and data maps — from a JSON scene the assistant writes.

What you can do
  • Render a scene to MP4, GIF, PNG or JPG and get back the file path, the imagery credit line and a preview of the final frame
  • Preview a single frame as an image to check framing, colours and labels before rendering a video
  • Style highlights with tint, spotlight, outline or flag fill on satellite, Blue Marble, Sentinel or parchment basemaps
  • Animate cameras: push-in, zoom-in, 3D globe dive, or flights between countries
  • Colour countries by numeric values with a legend, and mark capitals or named cities
When to use it
Useful when you want explainer, documentary or short-form map visuals generated from a description: a globe spinning and landing on a country, a highlighted region with its flag, or a choropleth-style data map, without editing video by hand.
Requirements
Runs locally over stdio, typically via npx with the mcp argument. The first run downloads Chromium and map data (both cached), and video output needs ffmpeg installed. No accounts, API keys or environment variables are declared.
Before you install
Rendering writes files to disk at the path you choose, and video rendering is CPU-heavy (roughly 15 seconds for a 5-second 1080p clip). The returned imagery credit line must be shown wherever the video is published. Disputed borders are drawn per the highlighted country's official view by default, which is a sensitive editorial choice.

Installation

In SourceWeft

  1. Open mapcast in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

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

json
{  "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

bash
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

json
{  "aspect": "16:9",  "duration": 5,  "camera": "push-in",  "highlights": [    { "country": "India", "style": "solid", "color": "#c8102e", "label": "INDIA" }  ]}
FieldValuesDefault
aspect16:9, 9:16, 1:1, 4:5 (or set width/height)16:9
durationseconds5 (7 for globe, 1 + 3 per country for fly)
fpsframes per second30
camerapush-in, zoom-in, globe (3D Earth dive), fly (country to country), static, or { "move", "fill", "from" }push-in
basemapsatellite, bluemarble, sentinel, paper (old parchment map)satellite
povauto (the country's own official borders), default, or a code like ind, chn, pakauto
effects.gradenatural, muted, mononatural
effects.vignette0 to 10.45
effects.blur0 to 1: soft-focus edges, like a camera lens0
effects.gridtrue or { "step", "color", "opacity" }: lat/long grid over the sea onlyoff
effects.borderstrue: thin borders of neighbouring countrieson for paper and states
labelAnimdefault label animation for every highlightrise

Each highlight:

FieldValuesDefault
countryname ("India") or ISO code ("IN", "IND")country or region required
regiona state or province: "California", "Bavaria", "US-CA", "IN-MH"
stylesolid (tinted fill), highlight (rest of the world goes grey), outline, flag (the country's flag over the terrain)solid
colorany CSS colour or red, yellow, blue, ...a distinct colour per country
labeltext, or false for nonethe country name
border{ "color", "width", "glow" } or falsewhite, glowing
labelAnimrise, type (typewriter), spread (letters close in), slide, poprise
labelSizemultiplier on the automatic label size, e.g. 0.7 or 1.31
labelFontsans, serif, or any font namesans (serif on paper)
capitaltrue for the capital (a state's own capital for region), or a city name like "Mumbai"off
startseconds when this country starts animatingstaggered automatically

Data maps

Colour countries by a number, with a legend:

json
{  "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]

Source: README.md at commit 3bef8e8

Tools

2

render_map

Render an animated map video (.mp4, .gif) or image (.png, .jpg) and save it to disk. Returns the file path, the imagery credit line (must be shown wherever the video is published) and a small preview of the final frame. Highlights countries on real satellite imagery (or an old paper map) with a tracing border, colour fill, glow and label, the look of documentary/explainer YouTube videos. Write a scene: { "highlights": [{ "country": "India" }] } is a complete one. Add only what the request asks for; defaults look good. Map requests to fields: a colour -> highlights[].color; "show the flag" -> style "flag"; "rest of the world grey/dark" -> style "highlight"; "just the border" -> style "outline"; "old map / history / parchment" -> basemap "paper"; "from space / the globe / spinning Earth" -> camera "globe"; "zoom in from far away" -> camera "zoom-in"; "travel/tour/go from X to Y" -> camera "fly" with highlights in visiting order; a state or province -> highlights[].region; "Shorts/Reels/TikTok/vertical" -> aspect "9:16"; "mark the capital" -> capital true; "compare countries by <number>" -> data.values with a title. Borders follow the highlighted country's official view of disputed areas (pov "auto"). A 5 second 1080p video takes roughly 10-30 seconds. Use preview_map first when unsure how a scene will look.

Parametersatscenerequiredoutput

preview_map

Quickly render one frame of a scene and return it as an image, without making a video. Use it to check framing, colours and labels before render_map. Highlights countries on real satellite imagery (or an old paper map) with a tracing border, colour fill, glow and label, the look of documentary/explainer YouTube videos. Write a scene: { "highlights": [{ "country": "India" }] } is a complete one. Add only what the request asks for; defaults look good. Map requests to fields: a colour -> highlights[].color; "show the flag" -> style "flag"; "rest of the world grey/dark" -> style "highlight"; "just the border" -> style "outline"; "old map / history / parchment" -> basemap "paper"; "from space / the globe / spinning Earth" -> camera "globe"; "zoom in from far away" -> camera "zoom-in"; "travel/tour/go from X to Y" -> camera "fly" with highlights in visiting order; a state or province -> highlights[].region; "Shorts/Reels/TikTok/vertical" -> aspect "9:16"; "mark the capital" -> capital true; "compare countries by <number>" -> data.values with a title. Borders follow the highlighted country's official view of disputed areas (pov "auto").

Parametersatscenerequired

Version history

1
  1. v0.1.1LatestOct 31, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts