Magic Lane MCP Server

Introduction

The Magic Lane Model Context Protocol (MCP) Server enables any AI agent or application to become a geospatially intelligent assistant, capable of acting as a reliable companion for pedestrians, cyclists, and drivers alike.

Built on top of Magic Lane's advanced mapping and routing technology, this TypeScript-based MCP server empowers AI agents to:

• Understand and process geospatial data,
• Interpret user intent in a spatial context,
• Deliver accurate, contextually relevant navigation guidance.

By leveraging Magic Lane's global map data and real-time geospatial intelligence, the MCP Server enables deeply personalized navigation and trip-planning experiences through core tools:

• Intelligent Search - Find addresses, points of interest (POIs), or coordinates with intelligent search capabilities and POI category filtering.

• Smart Routing - Generate optimized routes between multiple waypoints with support for various transport modes, route preferences, and dynamic POI integration.

• Round Trip Planning - Create circular routes that start and end at the same location, perfect for jogging routes, cycling loops, or delivery runs.

• Reverse Geocoding - Convert geographic coordinates into detailed address information including street name, city, state, country, and postal code.

• Isochrone Analysis - Calculate reachability polygons showing areas accessible within specific time or distance constraints.

• Route Visualization - Create visual map images of calculated routes, isochrones, and round trips for immediate geographical context and presentation.

• Geofence Management - Create, manage, and query geographic boundaries for asset monitoring, location-based alerts, and spatial analysis with support for polygons, circles, and rectangles.

• Interactive Map - Display an interactive vector tile map directly inside the conversation using MapLibre GL JS and MagicLane vector tiles. Supports location views, route visualization, isochrone overlays, round trip routes, and search result markers with pan/zoom interactions.

The map functionalities can be visualized as high-quality map images through our new beta feature:

• Static Map Rendering - Generate custom map views with markers, bounding boxes, or location-centered areas without route calculation, complementing route visualization for routes, isochrones, and round trips.

Together, these capabilities enable AI agents to act as true geospatial copilots - understanding spatial context, anticipating user needs, and optimizing every journey with precision and ease.

Transport Options: The server supports both stdio (for MCP-native clients like Claude Desktop) and HTTP (for web applications, serverless deployments, and custom integrations).

Getting Started

Prerequisites

The Magic Lane MCP Server integrates seamlessly with any AI application or agent, providing access to geospatial data and navigation functionality. Before setup, ensure you have the following:

System Requirements:

1. Node.js 22+ installed (Download here)
2. npm (comes with Node.js)
3. A valid Magic Lane API Key (for access to map data)
4. An MCP-compatible AI client, such as:
   • Claude Desktop
   • Cursor IDE
   • Visual Studio Code with GitHub Copilot

Verify Prerequisites:

# Check Node.js version (should be 22+)
node --version

# Check npm version
npm --version

Quick Start

For immediate testing, use npx to run the server without installation:

# Set your API key as environment variable
export MAGICLANE_API_KEY="your_api_key"

# Run the server directly
npx @magiclane/mcp-server

API Key Setup

To obtain a Magic Lane API token, follow our step-by-step guide. The detailed steps are:

1. Create a Magic Lane Account

   • Visit developer.magiclane.com/api/register and register for a free account.

2. Generate an API Key

   • Log in to your account
   • Navigate to the Projects Dashboard
   • Follow the instructions to generate your unique API key, which will serve as your access token for the MCP Server

Installation

To explore and integrate the MCP Server locally, follow these steps to install dependencies and build the project:

# Clone or navigate to the Magic Lane MCP Server directory
cd path/to/magiclane-mcp/mcp-server

# Install dependencies
npm install

# Build the TypeScript project
npm run build

# Verify the build was successful
ls dist/  # Should show map-server.esm.js and other compiled files

Note: Ensure Node.js 22+ and npm are properly installed before running these commands.

Running the Server

Standard MCP Server (stdio transport):

# Option 1: Using .env file (recommended)
cp .env.example .env
# Edit .env with your actual API key
npm start

# Option 2: Using Node's built-in env file support
node --env-file=.env dist/map-server.esm.js

# Option 3: Using environment variable directly
MAGICLANE_API_KEY=your_api_key npm start

HTTP Server (for web and custom clients):

# Development mode (with auto-reload)
npm run dev:http

# Production mode (after build)
npm run start:http

For complete HTTP server documentation including endpoints, JSON-RPC examples, and client integration, see the HTTP Server Setup Guide.

Configuration

Configure your MCP client to connect to the Magic Lane server. Follow the detailed setup guide for your specific AI client:

• Claude Desktop Setup Guide - Complete configuration instructions for Claude Desktop
• Cursor AI Setup Guide - Step-by-step setup for Cursor IDE
• VS Code Setup Guide - Integration guide for Visual Studio Code with GitHub Copilot

Each guide includes:

• Client-specific configuration file locations
• Multiple installation options (local build, NPM, Docker)
• Platform-specific instructions (Windows, macOS, Linux)

Docker

Build and run the server using Docker:

# Build the Docker image
docker build -t magiclane-mcp-server .

# Run the container (pass API key via environment variable)
docker run --rm -e MAGICLANE_API_KEY=your_api_key magiclane-mcp-server

# Or use an env file
docker run --rm --env-file .env magiclane-mcp-server

Environment Variables:

| Variable | Required | Description | | ------------------- | -------- | ------------------------------------------ | | MAGICLANE_API_KEY | Yes | Your Magic Lane API key for authentication |

The container runs with --enable-source-maps for better stack traces in production.

Available Tools

The Magic Lane MCP Server provides several integrated geospatial tools that enable AI systems to search, plan, analyze, and visualize routes and locations.

Looking for rendered map images and live interactive map demos? See Visual Examples.

1. Location Search

The Location Search Tool uses the Magic Lane Search REST API to find:

• Coordinates, addresses, or administrative areas.
• Points of Interest (POIs) around a reference location (restaurants, gas stations, pharmacies, etc.).

Input Parameters

| Parameter | Type | Default | Description | | :---------------------: | :-----: | :---------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | text | string | - | Free-text query (e.g., city, address, or landmark) | | poi_categories | array | [] | List of POI categories to filter results. Valid categories include gas_stations, food&drink, medical_services, shopping, education, public_transport, sightseeing, entertainment, and others | | target | array | addresses | Defines the result categories to return ( addresses, POIs, or both). | | reference_location | string | - | Coordinates or region used as search anchor | | language | string | "en" | Response language (ISO 3166 code) | | max_results | number | 5 | Maximum number of results | | estimate_house_number | boolean | true | Interpolates missing house numbers |

Example Prompts

• Urban Exploration & Tourism

  • "Search for authentic Italian restaurants in downtown Chicago within walking distance of Millennium Park."
  • "Where are the ATMs near Brandenburg Gate, Berlin?"

• Business & Logistics

  • "Locate the closest 'DHL Service Point' near Berlin Central Station."
  • "Find all Starbucks locations within 1km of our office at 1 Market Street, San Francisco."
  • "Where are the parking garages near Amsterdam Central Station?"

• Real Estate & Property

  • "Show all elementary schools near 456 Maple Avenue, Portland, Oregon with their exact distances from the property."
  • "Locate pharmacies, grocery stores, and public transport stops near the property at Baker Street 221B, London."

2. Routing Planner

The Routing Planner Tool generates optimized routes between multiple points using the Magic Lane Routing REST API and the Magic Lane Fleet Management Rest API. This tool supports the following capabilities:

• Point-to-point and multi-stop routing (A -> B -> C).
• Inclusion of POIs (e.g., gas stations, restaurants).
• Advanced VRP optimization for multi-delivery routes.
• Traffic, restriction, and terrain considerations.
• Multilingual route instructions.

Input Parameters

| Parameter | Type | Default | Description | | :----------------------: | :-----: | :---------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | transport | string | "car" | Transport type (car, lorry, truck, pedestrian, bike, public) | | type | string | "fastest" | Optimization type (fastest, shortest, economic, scenic) | | origin | string | - | Start location (name or coordinates) | | destination | string | - | End location (name or coordinates) | | intermediate_waypoints | array | [] | List of stops between start and end. Order determines route generation. Each waypoint defines specific preferences and constraints | | avoid | array | [] | Elements to avoid (highway, toll, ferry, unpaved, turnaround, traffic, roadblocks) | | vehicle | object | null | Vehicle characteristics including dimensions, weight, fuel type, EV parameters and profile preference. See Vehicle Specification for complete details | | details | string | "full" | Response detail level (full, basic) | | number_of_routes | number | 1 | Number of routes (1-3 car/bike; <= 11 public transport) | | fitness_factor | number | 0.5 | Bike / pedestrian terrain preference (0-1) | | emergency_status | boolean | false | Enable emergency vehicle mode | | language | string | "en" | Output language |

Intermediate Waypoint Structure

| Parameter | Type | Default | Description | | :-------------------: | :----: | :--------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | location | string | - | Location or address of the stop; can also specify a POI category | | location_preference | string | "close to departure" | Preferred placement of this stop along the route. Options: close to destination, close to departure, midpoint of the route, static location, no matter | | maximum_deviation | number | 500 | Maximum allowed deviation (in meters) |

Example Prompts

• International Travel & Tourism

  • "Generate a scenic bike route from Vienna to Bratislava, avoiding highways."
  • "Plan a road trip from Munich to Venice with stops at Innsbruck and Bolzano, optimized for scenic views."

• Public Transit & Commuting

  • "Find a public transport route from London to Oxford with minimal transfers."
  • "What's the quickest way to get from JFK Airport to Manhattan using public transport?"

• Multi-Stop Sightseeing & Events

  • "Create a walking tour from the Colosseum to the Trevi Fountain, stopping at the Pantheon and a gelato shop."
  • "I'm at the Eiffel Tower and need to visit Notre-Dame, Louvre Museum, and return to my hotel near Gare du Nord. Plan the best route by car."

• Emergency & Priority Routing

  • "Find the fastest route from St. John Ambulance Station, Westminster to General Hospital, avoiding traffic and roadblocks."
  • "Calculate the quickest route for emergency services from Fire Station 23 to the reported incident at Pike Place Market."

• Electric Vehicle Routing

  • "I'm driving a Tesla Model 3 with 60% battery from San Francisco to Los Angeles. Find the optimal route with necessary charging stops, ensuring I arrive with at least 20% charge."
  • "Calculate a route for my electric van (80 kWh battery, 250km range) from Berlin to Prague with fast-charging stops along the way."

3. Isochrone Calculator

The Isochrone Calculator Tool provides spatial analysis to determine all areas reachable from a reference point within specific travel time or distance constraints using the Magic Lane Isochrones REST API. This enables AI systems to analyze accessibility zones, service coverage areas, and reachability studies.

Key Features:

• Calculate reachability polygons based on time or distance constraints
• Support for multiple transport modes (walking, cycling, driving, public transport)
• Departure location resolution through coordinates or geocoding
• Multi-range analysis for complex accessibility studies

Input Parameters

| Parameter | Type | Default | Description | | :---------: | :----: | :---------: | ------------------------------------------------------------------------------------------------ | | transport | string | "car" | Transport mode (car, bike, pedestrian) | | type | string | "fastest" | Routing type (fastest, shortest, economic, scenic) | | departure | string | - | Starting point location (name or coordinates) | | ranges | array | - | Range list (meters if type is shortest, seconds if type is fastest) | | avoid | array | [] | Elements to avoid (highway, toll, ferry, unpaved, turnaround, traffic, roadblocks) | | locale | string | "en" | Result language (ISO 639-1 language code) |

Example Prompts

• "Where can I cycle to in 45 minutes from Amsterdam Central Station?"
• "Display all areas within a 10-minute walk from Atlantic Avenue-Barclays Center Station in Brooklyn."
• "Display the 1-hour driving catchment area from the proposed warehouse location in Frankfurt."

4. Round Trip Planner

The Round Trip Planner Tool generates circular routes that start and end at the same location. This tool is perfect for creating exploration routes, cycling loops, jogging paths, and delivery runs.

Key Features:

• Circular routes with guaranteed return to starting point
• Time-based or distance-based route generation
• Support for multiple transport modes (walking, cycling, driving)
• Terrain and hill skip preferences for cyclists
• Customizable route length and complexity

Input Parameters

| Parameter | Type | Default | Description | | :-----------: | :----: | :---------: | ------------------------------------------------------------------------------------------------ | | transport | string | "car" | Transport mode (car, bike, pedestrian) | | type | string | "fastest" | Routing type (fastest or shortest) | | departure | string | - | Starting point location (name or coordinates) - also the return destination | | range | number | - | Route range (meters if type is shortest, seconds if type is fastest) | | avoid | array | [] | Elements to avoid (highway, toll, ferry, unpaved, turnaround, traffic, roadblocks) | | random_seed | number | 0 | Seed for route generation reproducibility | | locale | string | "en" | Result language (ISO 639-1 language code) |

Example Prompts

• Fitness & Recreation

  • "Create a 10km jogging loop starting from Central Park."
  • "Design a 90-minute bike ride loop from Stephansplatz."

• Tourism & Exploration

  • "Generate a 45-minute walking loop from the Eiffel Tower."
  • "Plan a 2-hour walking loop starting from Times Square."

• Cycling Routes

  • "Create a 25km bike loop from Whistler Village, avoiding highways."
  • "Design a 1-hour cycling loop from Golden Gate Park using the shortest route."

5. Reverse Geocoding

The Reverse Geocoding Tool converts geographic coordinates or areas into detailed address information using the Magic Lane Reverse Geocoding REST API. This tool provides comprehensive address components for various spatial queries.

Key Features:

• Point-to-address conversion for specific coordinates
• Search around a point, within an area, or along a path
• Returns multiple address results with distance ranking
• Includes administrative hierarchy (settlement, city, county, state, country)
• Identifies nearby points of interest

Input Parameters

| Parameter | Type | Default | Description | | :-----------: | :----: | :-----: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | coordinates | object | - | Specific coordinate point { longitude, latitude } for address lookup | | insideArea | object | - | Area definition: bounding box (bbox) with east, west, north, south boundaries; circular area with center and radius meters; or polygon from polyline string or coordinate array (minimum 3 points) | | along | object | - | Path definition (encoded polyline or coordinates) with radius in meters to find addresses along | | limit | number | 5 | Maximum number of results to return | | locale | string | "en" | Result language (ISO 639-2/639-3 language code) |

Example Prompts

• "What's the address at coordinates 51.5074, -0.1278?"
• "Find all addresses within a 500-meter radius of the Brandenburg Gate."

6. Geofence Manager

The Geofence Manager Tool provides comprehensive geofence operations for defining and managing geographic boundaries, enabling location-based services and asset monitoring. This tool supports creating, retrieving, updating, deleting geofences, and checking if points fall within defined boundaries.

Key Features:

• Create geofences with polygon, circle, or rectangle geometries
• Query geofences by ID, within bounding boxes, or by proximity to a point
• Update geofence properties (name, keywords)
• Delete geofences by ID
• Check if specific coordinates fall inside geofences
• Support for custom metadata and tags

Operations & Parameters

Create Operation - Create one or more geofences with the following parameters:

| Parameter | Type | Default | Description | | :------------: | :----: | :-----: | -------------------------------------------------------------------- | | id | string | - | Custom identifier (auto-generated if not provided) | | name | string | - | Human-readable name | | keywords | array | [] | Tags for search and filtering | | properties | object | - | Additional custom metadata | | geojson_type | string | - | Geometry type: polygon, circle, or rectangle | | geojson_area | object | - | Area definition (polygon coordinates, circle center/radius, or bbox) |

Read Operation - Retrieve one or more geofences with the following parameters:

| Parameter | Type | Default | Description | | :--------------: | :----: | :-----: | ---------------------------------------------------------------- | | geofence_ids | array | - | Array of geofence IDs to retrieve | | box_limited | object | - | Bounding box filter (north, south, east, west) | | proximity_area | object | - | Search geofences near a point (reference_point, distance, limit) |

Update Operation - Modify properties of an existing geofence with the following parameters:

| Parameter | Type | Default | Description | | :-----------: | :----: | :-----: | ------------------------------------------ | | geofence_id | string | - | ID of geofence to update | | name | string | - | Human-readable name to update the geofence | | keywords | array | [] | Updated keywords/tags for geofence area |

Delete Operation - Remove one or more geofences with the following parameters:

| Parameter | Type | Default | Description | | :------------: | :---: | :-----: | ------------------------------- | | geofence_ids | array | - | Array of geofence IDs to delete |

Check Point Operation - Determine if coordinates fall within geofences with the following parameters:

| Parameter | Type | Default | Description | | :------------: | :---: | :-----: | ----------------------------------------------------------- | | geofence_ids | array | - | Array of geofence IDs to check against | | points | array | - | Array of locations to test (coordinates or location search) |

Example Prompts

• Asset Monitoring & Tracking

  • "Create a circular geofence with 500m radius around our warehouse at 123 Main Street, Chicago."
  • "Is the delivery vehicle at coordinates 40.7589, -73.9851 inside of Main Street zone geofence?"

• Restricted Area Management

  • "Create a rectangular 'construction-zone-1' geofence covering downtown Seattle bounded by these coordinates: north 47.6205, south 47.5990, east -122.3250, west -122.3450."
  • "Update the 'construction-zone-1' geofence to include 'temporary' and 'high-priority' keywords."

• Service Area & Delivery Zones

  • "Create three circular delivery zone geofences: 'berlin-warehouse-1' at coordinates 13.3777, 52.5163 with 2km radius, 'berlin-warehouse-2' at 13.4050, 52.5200 with 1.5km radius, and 'berlin-warehouse-3' at 13.3888, 52.5170 with 2.5km radius."
  • "Show me all geofences within 2km of Brandenburg Gate at coordinates 13.3777, 52.5163."
  • "Retrieve all geofences with IDs: 'zone-premium-01', 'zone-premium-02', and 'zone-premium-03' that are tagged with 'premium-service'."

• Location-Based Alerts

  • "Delete the temporary event geofences with IDs: 'summer-festival-2025-main', 'summer-festival-2025-parking', and 'summer-festival-2025-stage' now that the event is over."
  • "List all geofences within the bounding box covering Manhattan: north 40.8820, south 40.7006, east -73.9070, west -74.0479."
  • "Find all geofences near Times Square within 1000 meters and show their names and keywords."

7. Static Map Renderer

The Renderer Tool generates static map images of calculated routes, isochrones, round trips, and custom map views using the Magic Lane rendering service. It delivers immediate visual context by overlaying geographic data on a map and returning the result as an embedded image.

Key Features:

• Renders routes, isochrones, and round trips as PNG (default), JPEG, or WebP images
• Automatically calculates the optimal viewport to frame all relevant data
• Generates static map views centered on a location or bounded by custom coordinates
• Delivers images directly to the MCP client as base64-encoded data

Input Parameters

| Parameter | Type | Default | Description | | :-------------: | :----: | :-----------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | render_type | string | - | Visualization type: routing, isochrone, round_trip, or map_location | | output_format | string | "image/png" | Output image format: image/png (default), image/jpeg, or image/webp | | parameters | object | - | Parameters matching the selected render_type. For routing, isochrone, and round_trip, accepts the same parameters as the respective calculation tool. For map_location: width (px, default 800), height (px, default 600), corners ([minLon, minLat, maxLon, maxLat]) to fit a bounding box, or around_location (referenceLocation + distance radius in meters, default 500) to center on a point. |

Example Prompts

• Route representation

  • "I'm at 10 Downing Street, London - please show a driving route to St Paul's Cathedral."

• Round Trip representation

  • "Visualize a 5.5km jogging route starting from the Rijksmuseum in Amsterdam."

• Isochrone representation

  • "Please display a map of Paris with a 15-minute walking isochrone."

• Static Map representation

  • "Display a wide view of Miami, including beach and the Art Deco Historic District."

See Visual Examples for rendered output of these prompts.

8. Interactive Map

The Interactive Map Tool renders MagicLane vector tiles in a fully interactive map directly inside the conversation using MapLibre GL JS and MCP Apps. Unlike the static renderer, users can pan, zoom, and explore the map widget without leaving the chat client.

Key Features:

• Streams live vector tiles from MagicLane's global map service
• Automatically fits the viewport to the displayed data — location, route, isochrone, round trip, or search results
• Supports pan and zoom interactions within MCP Apps-compatible clients

Input Parameters

| Parameter | Type | Default | Description | | :------------: | :----: | :-----: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | display_type | string | - | Display mode: location, routing, isochrone, round_trip, or search_results | | zoom | number | 12 | Map zoom level (0 = world view, 16 = street level). Ignored for routing, isochrone, and round_trip — viewport is auto-fitted to the data. | | parameters | object | - | Accepts the same parameters as the corresponding calculation tool. Renders routes with full path visualization, reachability polygons as shaded areas, or circular routes with marked start/end points, depending on the selected display_type. |

Example Prompts

• Location View

  • "Show me an interactive map centered on the Eiffel Tower"
  • "Display an interactive map of downtown Tokyo."

• Route Visualization

  • "Show an interactive map of the driving route from Amsterdam to Brussels."
  • "Display a bike route from Central Park to Brooklyn Bridge on an interactive map, including a stop to pharmacy."

• Isochrone Overlay

  • "Show on an interactive map everywhere I can reach by car in 30 minutes from Berlin Central Station."
  • "Display a walking isochrone of 20 minutes from Trafalgar Square on an interactive map."

• Round Trip

  • "Show a 10 km jogging loop from Vondelpark on an interactive map."

• Search Results

  • "Show all coffee shops near the Louvre on an interactive map."
  • "Display restaurants within 1 km of Notre-Dame on an interactive map."

Browse runnable HTML demos for each display_type in Visual Examples.

Troubleshooting

Common Issues

Server Won't Start

# Check if Node.js version is 22+
node --version

# Verify API key is set
echo $MAGICLANE_API_KEY

# Check for build errors
npm run build

API Key Issues

• Ensure your API key is valid and active in the Magic Lane Dashboard
• Verify the environment variable is correctly set: MAGICLANE_API_KEY=your_key
• Check for extra spaces or quotes in the API key

Connection Problems

• Verify your MCP client configuration matches the server path
• Ensure the server is running before connecting the client
• Check firewall settings if using remote connections

Rate Limiting

• Magic Lane API has rate limits; check your dashboard for current usage
• Implement request caching for frequently accessed routes
• Consider upgrading your API plan if limits are exceeded

Common Error Messages

• Unauthorized access (401): Invalid API key. Check your configuration.
• No results found (404): The location could not be found. Try a different query.
• Too many requests (429): Rate limit exceeded. Check your usage dashboard.
• Bad request (400): Invalid parameters. Check your input format.

Privacy Policy

Magic Lane is committed to protecting your privacy and handling your data responsibly. For complete privacy information, see our full privacy policy: https://www.magiclane.com/web/terms-and-conditions#privacy

Data Collection

• Query data: Location search terms, route origins/destinations, and coordinates submitted through the MCP server are transmitted to Magic Lane's API for processing. They are not stored or logged by Magic Lane after the response is delivered.
• API key: Your API key is transmitted with every request solely for authentication and rate limiting. It is never shared with third parties.
• No user profiling: Magic Lane does not build user profiles, track usage patterns across sessions, or correlate individual requests.

How Data Is Used

• All requests are processed in real-time to generate the requested geospatial response (route, search result, isochrone, etc.).
• Processed data is immediately discarded after the response is delivered.
• Map rendering is performed dynamically; generated images are not retained after transmission.

Data Storage & Retention

• Magic Lane does not persistently store the content of routing requests, location queries, search parameters, or reverse geocode inputs.
• No session data or request history is retained on Magic Lane servers.

Third-Party Data

• Magic Lane uses OpenStreetMap data and other publicly available geographic datasets
• No personal or proprietary location data is shared with third parties
• Traffic and routing data is aggregated and anonymized at the source

For detailed information, review our Terms of Service and Privacy Policy.

Support

• Documentation: developer.magiclane.com/docs
• API Dashboard: developer.magiclane.com/api/dashboard
• GitHub Issues: github.com/magiclane/magiclane-mcp-server/issues
• Developer Portal Support: Contact support through the developer portal