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.

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.

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 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_mode	string	"car"	Transport mode (car, bike, pedestrian)
routing_type	string	"fastest"	Routing type (fastest, shortest, economic, scenic)
departure	string	-	Starting point location (name or coordinates)
ranges	array	-	Range list (meters if routing type is shortest, seconds if routing type is fastest)
avoid	array	[]	Elements to avoid (highway, toll, ferry, unpaved, turnaround, traffic, roadblocks)
language	string	"en"	Result language (ISO 3166-1_3 or ISO 3166-1_2)

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_mode	string	"car"	Transport mode (car, bike, pedestrian)
routing_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 routing type is shortest, seconds if routing type is fastest)
avoid	array	[]	Elements to avoid (highway, toll, ferry, unpaved, turnaround, traffic, roadblocks)
random_seed	number	0	Seed for route generation reproducibility
language	string	"en"	Result language (ISO 3166-1)

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
at	object	-	Specific coordinate point [longitude, latitude] for address lookup
in	object	-	Area definition using a rectangular area defined by east, west, north, south boundaries, circular area defined by center coordinates and radius in meters or a custom area defined by 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
language	string	"en"	Result language (ISO 3166-1)

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

The Renderer Tool generates visual map images of calculated routes, isochrones, round trips, and static maps using the Magic Lane rendering service. This tool provides immediate geographical context by creating images that display geographic data overlaid on maps.

Key Features:

• Visual route/isochrone/round-trip representation as PNG (default), JPEG, or WebP format (modern, efficient)
• Automatic viewport calculation for optimal map framing
• Static map generation with custom bounding boxes or location-centered views
• Embedded in MCP client as base64-encoded images

Input Parameters

Routing, Isochrone, and Round Trip: Uses the same parameters as their respective calculation tools to render calculated routes with full path visualization, reachability polygons as colored areas, or circular routes with start/end point.

Static Map:

Parameter	Type	Default	Description
width	number	800	Image width in pixels (200-2000)
height	number	600	Image height in pixels (200-2000)
corners	array	-	Bounding box as [minLon, minLat, maxLon, maxLat]
around_location	object	-	Reference location with distance for centered view

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.

---

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