static-map
Generate PNG map images with customizable markers, routes, and styles using Stadia Maps Location API MCP Server. Ideal for visualizing locations, boundaries, or paths in static map formats.
Instructions
Generate a PNG map image of an area, optionally including markers and a line (e.g. to draw a route or a boundary)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| encodedPolyline | No | The encoded polyline representing the route (precision 6). Optional, but either markers or a polyline must be specified. | |
| markers | No | Markers to add to the map. Optional, but either markers or a polyline must be specified. | |
| strokeColor | No | Optional color for the polyline (hex code or CSS color name; e.g. FFFFFF or blue). | |
| strokeWidth | No | Optional width for the route line in pixels. | |
| style | No | The Stadia Maps style slug to use. | outdoors |
Implementation Reference
- src/tools/staticMaps.ts:79-123 (handler)The main handler function for the 'static-map' tool. It constructs a payload for the Stadia Maps Static Maps API, including optional encoded polyline for routes, stroke properties, and markers, then calls the helper to fetch and return the map as a base64-encoded PNG image.export async function staticMap({ style = DEFAULT_STYLE, encodedPolyline, strokeColor, strokeWidth, markers, }: StaticMapParams): Promise<CallToolResult> { const payload: any = { // Fixed at 600x400; customize as needed size: "600x400@2x", lines: [], }; // Add line if provided if (encodedPolyline) { // Create the line object const line: any = { shape: encodedPolyline, }; // Add optional line properties if provided if (strokeColor) line.stroke_color = strokeColor; if (strokeWidth) line.stroke_width = strokeWidth; payload.lines.push(line); } // Add markers if provided if (markers && markers.length > 0) { payload.markers = markers.map((marker) => { const markerObj: any = { lat: marker.lat, lon: marker.lon, }; if (marker.label) markerObj.label = marker.label; if (marker.color) markerObj.color = marker.color; if (marker.markerUrl) markerObj.style = `custom:${marker.markerUrl}`; return markerObj; }); } return generateStaticMapAsCallToolResult(payload, style); }
- src/index.ts:103-140 (registration)Registration of the 'static-map' tool using McpServer.tool(), including name, description, input schema (using Zod schemas), and reference to the staticMap handler function.server.tool( "static-map", "Generate a PNG map image of an area, optionally including markers and a line (e.g. to draw a route or a boundary)", { style: mapStyleSchema, encodedPolyline: z .string() .describe( "The encoded polyline representing the route (precision 6). Optional, but either markers or a polyline must be specified.", ) .optional(), strokeColor: z .string() .describe( "Optional color for the polyline (hex code or CSS color name; e.g. FFFFFF or blue).", ) .optional(), strokeWidth: z .number() .describe("Optional width for the route line in pixels.") .optional(), markers: z .array( z.object({ lat: latitudeSchema, lon: longitudeSchema, label: markerLabelSchema, color: markerColorSchema, markerStyle: markerStyleSchema, }), ) .describe( "Markers to add to the map. Optional, but either markers or a polyline must be specified.", ) .optional(), }, staticMap, );
- src/schemas.ts:77-82 (schema)Zod schema for the 'style' parameter used in the static-map tool.export const mapStyleSchema = z // See https://docs.stadiamaps.com/themes/ for more styles! .enum(["outdoors", "alidade_smooth", "alidade_smooth_dark"]) .describe("The Stadia Maps style slug to use.") .default(DEFAULT_STYLE);
- src/tools/staticMaps.ts:31-74 (helper)Helper function that makes the API call to Stadia Maps Static Maps endpoint, handles errors, converts the PNG response to base64, and formats as MCP CallToolResult.async function generateStaticMapAsCallToolResult( payload: any, style: string, ): Promise<CallToolResult> { return handleToolError( async () => { const url = `${STATIC_MAPS_BASE_URL}/${style}?api_key=${API_KEY}`; const response = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify(payload), }); if (!response.ok) { throw new Error( `HTTP code: ${response.status}.\nPayload: ${JSON.stringify(payload)}`, ); } // Get the image as a buffer const imageBuffer = await response.arrayBuffer(); // Convert to base64 const base64Image = Buffer.from(imageBuffer).toString("base64"); return { content: [ { type: "image", data: base64Image, mimeType: "image/png", }, ], }; }, { contextMessage: "Failed to generate static map", enableLogging: true, }, ); }
- src/tools/staticMaps.ts:14-26 (helper)TypeScript type definition matching the input parameters for the staticMap handler.export type StaticMapParams = { style?: string; encodedPolyline?: string; strokeColor?: string; strokeWidth?: number; markers?: Array<{ lat: number; lon: number; label?: string; color?: string; markerUrl?: string; }>; };