Azure Maps MCP Server

A Model Context Protocol (MCP) server implementation that provides Azure Maps functionality as tools for Large Language Models (LLMs). This server exposes the full range of Azure Maps services including search, routing, rendering, and geolocation capabilities.

Overview

This project implements an MCP server using Azure Functions that integrates with Azure Maps services. It allows LLMs to perform a wide range of geographic operations including:

• Geocoding & Search: Convert addresses or place names to coordinates and vice versa
• Routing: Calculate routes, travel times, and reachable areas
• Map Rendering: Generate map tiles and static map images
• Geolocation: Determine country codes and location info from IP addresses

Features

🗺️ Search & Geocoding

Convert street addresses, landmarks, or place names to geographic coordinates with detailed address information:

• Geocoding: Address → Coordinates with detailed properties
• Reverse Geocoding: Coordinates → Human-readable addresses
• Administrative Boundaries: Retrieve polygon boundaries for cities, postal codes, states, countries
• Confidence scores, match codes, and comprehensive address details

�️ Routing & Navigation

Calculate optimal routes and analyze travel patterns:

• Route Directions: Turn-by-turn navigation between multiple points
• Route Matrix: Calculate travel times/distances between multiple origins and destinations
• Route Range (Isochrone): Find areas reachable within time or distance budgets
• Support for multiple travel modes (car, truck, bicycle, pedestrian, etc.)
• Traffic-aware routing and route optimization options

🖼️ Map Rendering & Visualization

Generate visual map content and tiles:

• Map Tiles: Retrieve individual map tiles for custom mapping applications
• Static Map Images: Generate map snapshots with custom markers and paths
• Tile Metadata: Access tile set information and coordinate systems
• Tile Coordinates: Convert between geographic and tile coordinate systems
• Support for road, satellite, and hybrid map styles

🌐 Geolocation & IP Analysis

Determine geographic information from IP addresses:

• IP Geolocation: Get country codes from IPv4/IPv6 addresses
• Batch IP Processing: Process multiple IP addresses efficiently
• IP Validation: Validate IP address formats and get technical details
• Support for both public and private IP address analysis

Prerequisites

• .NET 9.0 SDK
• Azure Functions Core Tools
• Azure Maps subscription key

Setup

1. Get Azure Maps Subscription Key

1. Create an Azure Maps account in the Azure Portal
2. Create a new Azure Maps resource
3. Copy the subscription key from the resource's authentication settings

2. Configure Environment

Create or update the source/local.settings.json file with your Azure Maps subscription key:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "None",
    "AzureWebJobsSecretStorageType": "Files",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
    "AZURE_MAPS_SUBSCRIPTION_KEY": "your-azure-maps-subscription-key-here"
  }
}

⚠️ Important: Never commit your actual subscription key to version control. Use environment variables or Azure Key Vault for production deployments.

Building the Project

Clean and Build

# Navigate to the project directory
cd source

# Clean the project
dotnet clean

# Restore dependencies and build
dotnet build

Using VS Code Tasks

If you're using VS Code, you can use the predefined tasks:

• Ctrl+Shift+P → "Tasks: Run Task" → "build (functions)"

Running the Server

Local Development

Option 1: Using Azure Functions Core Tools

# Navigate to the source directory
cd source

# Build the project first
dotnet build

# Start the function host
cd bin/Debug/net9.0
func host start

Option 2: Using VS Code

• Press F5 or use "Run and Debug" in VS Code
• Or run the task: Ctrl+Shift+P → "Tasks: Run Task" → "func: host start"

Option 3: Using .NET CLI

# Navigate to the source directory
cd source

# Run the application
dotnet run

The server will start on the default port (typically 7071 for Azure Functions, or 7174 as configured in launch settings).

Production Deployment

Azure Functions

Deploy to Azure Functions for production use:

# Publish the project
dotnet publish --configuration Release

# Deploy using Azure Functions Core Tools
func azure functionapp publish your-function-app-name

Usage

Once running, the MCP server exposes the following tools organized by service category:

🗺️ Search Tools

Geocoding

{
  "name": "geocoding",
  "description": "Convert street addresses or place names to longitude and latitude coordinates",
  "parameters": {
    "address": "string - Address or landmark name",
    "maxResults": "number - Maximum results to return (1-100, default: 5)"
  }
}

Reverse Geocoding

{
  "name": "reverse_geocoding", 
  "description": "Convert longitude and latitude coordinates to a street address",
  "parameters": {
    "latitude": "number - Latitude coordinate",
    "longitude": "number - Longitude coordinate"
  }
}

Get Polygon

{
  "name": "get_polygon",
  "description": "Get administrative boundary polygon for a specific location",
  "parameters": {
    "latitude": "number - Latitude coordinate",
    "longitude": "number - Longitude coordinate", 
    "resultType": "string - locality|postalCode1|adminDistrict1|adminDistrict2|countryRegion",
    "resolution": "string - small|medium|large"
  }
}

🛣️ Routing Tools

Get Route Directions

{
  "name": "get_route_directions",
  "description": "Calculate route directions between coordinates with turn-by-turn instructions",
  "parameters": {
    "coordinates": "array - Array of lat/lng objects for waypoints",
    "travelMode": "string - car|truck|bicycle|pedestrian (default: car)",
    "routeType": "string - fastest|shortest|eco (default: fastest)",
    "avoidTolls": "boolean - Avoid toll roads",
    "avoidHighways": "boolean - Avoid highways"
  }
}

Get Route Matrix

{
  "name": "get_route_matrix",
  "description": "Calculate travel times and distances between multiple origins and destinations",
  "parameters": {
    "origins": "array - Array of origin coordinate objects",
    "destinations": "array - Array of destination coordinate objects",
    "travelMode": "string - car|truck|bicycle|pedestrian (default: car)",
    "routeType": "string - fastest|shortest|eco (default: fastest)"
  }
}

Get Route Range

{
  "name": "get_route_range",
  "description": "Calculate reachable area within time or distance budget (isochrone)",
  "parameters": {
    "latitude": "number - Starting latitude",
    "longitude": "number - Starting longitude",
    "timeBudgetInSeconds": "number - Time budget (OR distanceBudgetInMeters)",
    "distanceBudgetInMeters": "number - Distance budget (OR timeBudgetInSeconds)",
    "travelMode": "string - car|truck|bicycle|pedestrian (default: car)"
  }
}

🖼️ Rendering Tools

Get Map Tile Set Metadata

{
  "name": "get_map_tileset_metadata",
  "description": "Get metadata for map tile sets including endpoints and zoom levels",
  "parameters": {
    "tileSetId": "string - microsoft.base.road|microsoft.imagery|microsoft.base.hybrid"
  }
}

Get Map Tile

{
  "name": "get_map_tile",
  "description": "Get a map tile image as base64-encoded PNG",
  "parameters": {
    "latitude": "number - Tile center latitude",
    "longitude": "number - Tile center longitude",
    "zoomLevel": "number - Zoom level (1-22, default: 10)",
    "tileSetId": "string - Map style (default: microsoft.base.road)",
    "tileSize": "number - 256 or 512 pixels (default: 256)"
  }
}

Get Static Map Image

{
  "name": "get_static_map_image",
  "description": "Generate static map image with optional markers and paths",
  "parameters": {
    "boundingBox": "object - {west, south, east, north} coordinates",
    "zoomLevel": "number - Zoom level (1-20, default: 10)",
    "width": "number - Image width in pixels (1-8192, default: 512)",
    "height": "number - Image height in pixels (1-8192, default: 512)",
    "markers": "array - Optional markers with lat/lng/label/color",
    "paths": "array - Optional paths with coordinates and styling"
  }
}

Get Tile Coordinates

{
  "name": "get_tile_coordinates",
  "description": "Calculate tile X,Y coordinates for geographic position",
  "parameters": {
    "latitude": "number - Latitude coordinate",
    "longitude": "number - Longitude coordinate",
    "zoomLevel": "number - Zoom level (1-22, default: 10)",
    "tileSize": "number - 256 or 512 pixels (default: 256)"
  }
}

🌐 Geolocation Tools

Get Country Code by IP

{
  "name": "get_country_code_by_ip",
  "description": "Get country code and location info for an IP address",
  "parameters": {
    "ipAddress": "string - IPv4 or IPv6 address to look up"
  }
}

Get Country Code Batch

{
  "name": "get_country_code_batch",
  "description": "Get country codes for multiple IP addresses",
  "parameters": {
    "ipAddresses": "array - Array of IP addresses (max 100)"
  }
}

Validate IP Address

{
  "name": "validate_ip_address",
  "description": "Validate IP address format and get technical details",
  "parameters": {
    "ipAddress": "string - IP address to validate"
  }
}

Project Structure

azure-maps-mcp/
├── source/
│   ├── azure-maps-mcp.csproj     # Project file with dependencies
│   ├── Program.cs                 # Application entry point and DI configuration
│   ├── host.json                  # Azure Functions host configuration
│   ├── local.settings.json        # Local development settings (not in repo)
│   ├── Services/
│   │   ├── IAzureMapsService.cs   # Service interface
│   │   └── AzureMapsService.cs    # Azure Maps client implementation
│   └── Tools/
│       ├── SearchTool.cs          # MCP tools for geocoding and search
│       └── RenderTool.cs          # (Reserved for future rendering tools)
└── README.md

Dependencies

• Azure.Maps.Search (2.0.0-beta.5): Azure Maps Search SDK
• Microsoft.Azure.Functions.Worker (2.0.0): Azure Functions runtime
• Microsoft.Azure.Functions.Worker.Extensions.Mcp (1.0.0-preview.6): MCP support for Azure Functions
• .NET 9.0: Target framework

Configuration

Environment Variables

• AZURE_MAPS_SUBSCRIPTION_KEY: Your Azure Maps subscription key (required)

Azure Functions Settings

• AzureWebJobsStorage: Set to "None" for local development
• FUNCTIONS_WORKER_RUNTIME: Set to "dotnet-isolated"

Troubleshooting

Common Issues

1. Missing subscription key: Ensure AZURE_MAPS_SUBSCRIPTION_KEY is set in your environment
2. Build failures: Make sure you have .NET 9.0 SDK installed
3. Function startup issues: Check that Azure Functions Core Tools are installed and up to date

Logs

The application uses structured logging. Check the console output for detailed error messages and operational information.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the terms specified in the LICENSE file.

Related Links

• Azure Maps Documentation
• Model Context Protocol Specification
• Azure Functions Documentation