stadiamaps -ts

This MCP server exposes Stadia Maps capabilities to an AI agent via the MCP protocol. It provides tools for geocoding (address lookup and place search), time information (current time and time zone data), static map image generation with markers and route overlays, routing and travel time, and isochrones (time and distance contours). With these tools, you can prompt the agent to geocode addresses, render maps, compute routes and travel times, or determine reachable areas within a given time or distance. The server relies on a Stadia Maps API key (provided via the API_KEY environment variable) to access the Stadia Maps APIs securely.

Typical usage patterns include asking the agent to geocode a list of addresses, generate a static map showing a route between two points, or fetch time zone information for a location. The integration examples outline how to connect to this MCP server from Claude Desktop, Warp, or via the Anthropic SDK for programmatic use. When prompting, you can nudge the model to select the appropriate Stadia Maps tool (e.g., geocoding vs. routing) to improve accuracy and reduce unnecessary API calls.

Prerequisites

• Node.js or Bun installed on your system (this project uses Bun in its quickstart).
• A Stadia Maps API key (required for API access).
• Git to clone the repository (if you are starting from source).

Installation steps

1. Clone the repository (or download the source):

git clone https://github.com/your-org/stadiamaps-stadiamaps-mcp-server-ts.git
cd stadiamaps-stadiamaps-mcp-server-ts

2. Install dependencies using Bun (recommended):

bun install

If you prefer npm, you can try:

npm install

3. Build the project (if applicable):

bun run build

4. Run the MCP server (requires API_KEY in the environment):

export API_KEY=your-stadia-maps-api-key
bun run start

5. Verify the server is running by hitting the configured endpoint (the README or docs will specify the default port, typically http://localhost:3000 or similar).

Environment variables and configuration:

• API_KEY must be set to a valid Stadia Maps API key, and is required for all API calls.

Tips:

• If you encounter rate limiting, consider batching requests or caching frequently accessed results client-side.
• The tool schema drives the context used by the LLM; keep the number of tools focused to reduce token costs. Start with geocoding and routing, then add time/isochrone features as needed.
• When prompting, be explicit about which Stadia Maps tool to use (e.g., routing vs. isochrones) to improve result fidelity.

Common issues:

• Missing API key: ensure API_KEY is exported in the environment when starting the server.
• Build failures: confirm your TypeScript compilation targets match your runtime, and that Bun is installed and configured correctly.
• Firewall or network restrictions can block API access; confirm outbound HTTP(S) access is allowed.