{"id":"557064f7-ebf7-4668-9def-d1a2aa37ebef","slug":"mapcast","kind":"mcp","name":"mapcast","summary":"Animated map videos for explainers and Shorts: highlight countries and states on satellite or paper maps, globe dive, camera flights. CLI, MCP server and AI skill.","owner":"21prnv","repoUrl":"https://github.com/21prnv/mapcast","license":"MIT","licenseTier":"permissive","trust":"community","stars":3,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-10-28T14:37:36.000Z","addedAt":"2026-10-31T15:57:44.847Z","logoUrl":"https://avatars.githubusercontent.com/u/110466571?u=6d576670694af1321d60b3728546fee876a75079&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["utilities","cloud-infra","design-media"],"tags":["animation","choropleth","explainer","geography","globe","map","satellite","video"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-31T20:46:36.421Z","sample":false,"url":"https://conduits.dev/tools/mapcast","language":"JavaScript","transports":["stdio"],"install":{"npm":"mapcast"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# mapcast\n\n**Animated map videos for explainers, documentaries and Shorts, from one line of JSON.**\nHighlight any country, state or province on real satellite imagery or an old paper map: tracing borders,\nflags, glow, labels, capitals, data colours, a 3D globe dive and camera flights between countries.\nFree, open source, and built for AI agents to drive.\n\n[![npm](https://img.shields.io/npm/v/mapcast)](https://www.npmjs.com/package/mapcast)\n[![licence: MIT](https://img.shields.io/badge/licence-MIT-blue)](LICENSE)\n\n![mapcast showcase: globe dive into India, France flag, paper map of Italy, unemployment data map, flight to Turkey](docs/showcase.gif)\n\n<sub>Full-quality version: [docs/showcase.mp4](docs/showcase.mp4)</sub>\n\n```bash\nnpx mapcast quick India -o india.mp4\n```\n\nThat is the whole setup. The first run downloads Chromium and map data once (both cached); videos also need\n[ffmpeg](https://ffmpeg.org/download.html).\n\n## Ask your AI for it\n\nmapcast is made to be driven by AI tools: you describe the map, the agent writes the scene, mapcast renders it.\n\n> \"Make a YouTube Short that spins the globe and lands on Brazil with its flag.\"\n> \"Old parchment map of Turkey, zooming in, with Istanbul marked.\"\n> \"Colour these countries by unemployment: Spain 11.4, Greece 9.8, Germany 3.4.\"\n\n**Claude Code** (skill and MCP server in one install):\n\n```\n/plugin marketplace add 21prnv/mapcast\n/plugin install mapcast@mapcast\n```\n\n**Claude Desktop, Cursor, Windsurf, Codex or any MCP client:** add this to the client's MCP config.\n\n```json\n{\n  \"mcpServers\": {\n    \"mapcast\": { \"command\": \"npx\", \"args\": [\"-y\", \"mapcast\", \"mcp\"] }\n  }\n}\n```\n\nThe server offers `render_map` (saves the video or image and returns a preview of the final frame, so the agent\ncan check its work) and `preview_map` (one frame, to check a scene before rendering). Every option is described\nin the tool schema.\n\n**Agents that read `SKILL.md` skills:** `npx skills add 21prnv/mapcast`. The skill is in\n[`skills/mapcast`](skills/mapcast), with [27 worked request-to-scene examples](skills/mapcast/references/examples.md).\n\n## What it can do\n\n![Gallery: globe, India, France flag, paper Italy, data map, Turkey](docs/gallery.jpg)\n\n- **Styles:** colour tint that keeps the terrain visible, spotlight (rest of the world turns grey), outline, or the\n  country's flag laid over its land.\n- **Basemaps:** NASA Blue Marble and Sentinel-2 satellite imagery, or an old parchment map with engraved coasts.\n- **Cameras:** slow push-in, zoom in from a wide view, dive from a spinning 3D globe, fly from country to country.\n- **Places:** every country by name or ISO code, plus 4,500 states and provinces (`\"California\"`, `\"IN-MH\"`), with\n  capitals or any city marked.\n- **Data maps:** colour countries by a number with a legend, with names and values on the map.\n- **Formats:** MP4, GIF, PNG, JPG in 16:9, 9:16, 1:1 or 4:5.\n- **Disputed borders:** drawn the way the highlighted country officially draws them, or a neutral view on request.\n\n## Command line\n\n```bash\nnpx mapcast quick \"United States\" --style highlight --color yellow -o usa.png\nnpx mapcast quick France --style flag -o france.mp4\nnpx mapcast quick Brazil --camera globe -o brazil.mp4          # dive in from a spinning Earth\nnpx mapcast quick India France Japan --camera fly -o tour.mp4   # fly from country to country\nnpx mapcast quick Italy --basemap paper -o italy.mp4\n\nnpx mapcast render scene.json -o out.mp4        # any scene; .mp4, .gif, .png or .jpg\nnpx mapcast render scene.json -o out.png --at 1.2\ncat scene.json | npx mapcast render - -o out.gif\nnpx mapcast schema                              # the scene format as JSON Schema\nnpx mapcast mcp                                 # MCP server on stdio\n```\n\nEvery file in [`examples/`](examples) renders as-is.\n\n## Scene format\n\n```json\n{\n  \"aspect\": \"16:9\",\n  \"duration\": 5,\n  \"camera\": \"push-in\",\n  \"highlights\": [\n    { \"country\": \"India\", \"style\": \"solid\", \"color\": \"#c8102e\", \"label\": \"INDIA\" }\n  ]\n}\n```\n\n| Field | Values | Default |\n|---|---|---|\n| `aspect` | `16:9`, `9:16`, `1:1`, `4:5` (or set `width`/`height`) | `16:9` |\n| `duration` | seconds | `5` (`7` for `globe`, `1 + 3` per country for `fly`) |\n| `fps` | frames per second | `30` |\n| `camera` | `push-in`, `zoom-in`, `globe` (3D Earth dive), `fly` (country to country), `static`, or `{ \"move\", \"fill\", \"from\" }` | `push-in` |\n| `basemap` | `satellite`, `bluemarble`, `sentinel`, `paper` (old parchment map) | `satellite` |\n| `pov` | `auto` (the country's own official borders), `default`, or a code like `ind`, `chn`, `pak` | `auto` |\n| `effects.grade` | `natural`, `muted`, `mono` | `natural` |\n| `effects.vignette` | 0 to 1 | `0.45` |\n| `effects.blur` | 0 to 1: soft-focus edges, like a camera lens | `0` |\n| `effects.grid` | `true` or `{ \"step\", \"color\", \"opacity\" }`: lat/long grid over the sea only | off |\n| `effects.borders` | `true`: thin borders of neighbouring countries | on for `paper` and states |\n| `labelAnim` | default label animation for every highlight | `rise` |\n\nEach highlight:\n\n| Field | Values | Default |\n|---|---|---|\n| `country` | name (`\"India\"`) or ISO code (`\"IN\"`, `\"IND\"`) | `country` or `region` required |\n| `region` | a state or province: `\"California\"`, `\"Bavaria\"`, `\"US-CA\"`, `\"IN-MH\"` | |\n| `style` | `solid` (tinted fill), `highlight` (rest of the world goes grey), `outline`, `flag` (the country's flag over the terrain) | `solid` |\n| `color` | any CSS colour or `red`, `yellow`, `blue`, ... | a distinct colour per country |\n| `label` | text, or `false` for none | the country name |\n| `border` | `{ \"color\", \"width\", \"glow\" }` or `false` | white, glowing |\n| `labelAnim` | `rise`, `type` (typewriter), `spread` (letters close in), `slide`, `pop` | `rise` |\n| `labelSize` | multiplier on the automatic label size, e.g. `0.7` or `1.3` | `1` |\n| `labelFont` | `sans`, `serif`, or any font name | `sans` (`serif` on paper) |\n| `capital` | `true` for the capital (a state's own capital for `region`), or a city name like `\"Mumbai\"` | off |\n| `start` | seconds when this country starts animating | staggered automatically |\n\n## Data maps\n\nColour countries by a number, with a legend:\n\n```json\n{\n  \"data\": {\n    \"title\": \"GDP 2024 (trillion US$)\",\n    \"prefix\": \"$\",\n    \"unit\": \"T\",\n    \"scheme\": \"heat\",\n    \"values\": { \"India\": 3.9, \"China\": 18.7, \"Japan\": 4.1 }\n  }\n}\n```\n\n`scheme` is one of `reds`, `blues`, `greens`, `heat`, `purples`, `diverging`, or a list of colours.\nSet `\"labels\"` to `\"name\"`, `\"value\"` (the number with `prefix`/`unit`) or `\"both\"` to label each country,\nand `min`/`max` to fix the colour range. A highlight's `label` can have a second line: `\"INDIA\\n1.4 BILLION\"`.\n\n## How it works\n\nA scene is resolved against [Natural Earth](https://www.naturalearthdata.com) borders, the imagery tiles the camera\npath needs are fetched and cached, and a headless Chromium draws each frame on a canvas (WebGL for the globe).\nFrames are piped to ffmpeg. A 5 second 1080p clip takes about 15 seconds on a laptop.\n\n## Credits and licence\n\nMIT. Map data, imagery and font licences are in [NOTICE.md](NOTICE.md). Satellite imagery needs a credit line\nwherever you publish; mapcast prints the exact line after every render.\n\nContributions are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n[![M8ven Score](https://m8ven.ai/badge/mcp/21prnv-mapcast-c8zmhu?v=4dfd1c8a9f0a5b65bfb0e33dc7df3784)](https://m8ven.ai/mcp/21prnv-mapcast-c8zmhu?s=readme)\n"}