QuantaRoute MCP Server

A Model Context Protocol (MCP) server that provides AI assistants (Claude Desktop, Cursor, and more) with powerful geocoding, location lookup, and DigiPin processing capabilities using the QuantaRoute Geocoding API.

Package: @quantaroute/mcp-server (MCP Server for AI Agents)
SDK: quantaroute-geocoding (Node.js/TypeScript SDK)

✅ Fully compatible with Claude Desktop and Cursor

Features

🗺️ Geocoding Tools

• Geocode addresses to DigiPin codes and coordinates
• Reverse geocode DigiPin codes to addresses
• Convert coordinates to DigiPin codes
• Validate DigiPin format and location
• Batch geocode multiple addresses (up to 100)
• Autocomplete address suggestions

🚀 Revolutionary Location Lookup with Nominatim + Pincode + Digipin

• Lookup administrative boundaries from coordinates (pincode, state, division, locality)
• Lookup from DigiPin codes
• Batch location lookup for multiple locations
• Find nearby boundaries within a radius [COMING SOON...]
• Access to 36,000+ postal boundaries across India

📊 Utility Tools

• Get API usage statistics
• Get location statistics (boundaries, states, divisions)
• Check API health status

Installation

This MCP server is compatible with Claude Desktop and Cursor. Follow the instructions below for your platform.

For Claude Desktop

1. Locate the Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Edit the configuration file and add:

{
  "mcpServers": {
    "quantaroute": {
      "command": "npx",
      "args": [
        "-y",
        "@quantaroute/mcp-server"
      ],
      "env": {
        "QUANTAROUTE_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Save and restart Claude Desktop to apply the changes.

For Cursor

Add to your MCP configuration file (~/.cursor/mcp.json):

{
  "mcpServers": {
    "quantaroute": {
      "command": "npx",
      "args": [
        "-y",
        "@quantaroute/mcp-server"
      ],
      "env": {
        "QUANTAROUTE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Restart Cursor after making changes.

Environment Variables

• QUANTAROUTE_API_KEY (required): Your QuantaRoute API key
  • Get your API key from: https://developers.quantaroute.com
  • Free tier test key: demo_free_key_123 (for testing)

Available Tools

geocode

Geocode an address to get DigiPin code and coordinates.

Parameters:

• address (required): The address to geocode
• city (optional): City name
• state (optional): State name
• pincode (optional): Postal code
• country (optional): Country name (defaults to India)

Example:

{
  "address": "Rohra Address, New Town",
  "city": "New Town",
  "state": "West Bengal",
  "pincode": "700163"
}

reverse_geocode

Reverse geocode a DigiPin code to get coordinates and address.

Parameters:

• digipin (required): DigiPin code (format: XXX-XXX-XXXX)

coordinates_to_digipin

Convert latitude and longitude to DigiPin code.

Parameters:

• latitude (required): Latitude (-90 to 90)
• longitude (required): Longitude (-180 to 180)

lookup_location_from_coordinates

🚀 REVOLUTIONARY: Get administrative boundaries from coordinates.

Returns: pincode, state, division, locality, district, population density, and more.

Parameters:

• latitude (required): Latitude coordinate
• longitude (required): Longitude coordinate

lookup_location_from_digipin

Get administrative boundaries from a DigiPin code.

Parameters:

• digipin (required): DigiPin code

batch_location_lookup

Batch lookup for multiple locations (up to 100).

Parameters:

• locations (required): Array of location objects
  • Each object can have latitude + longitude OR digipin

batch_geocode

Geocode multiple addresses in a single request (up to 100).

Parameters:

• addresses (required): Array of address objects

autocomplete

Get address autocomplete suggestions.

Parameters:

• query (required): Search query (minimum 3 characters)
• limit (optional): Max suggestions (default: 5, max: 10)

find_nearby_boundaries [COMING SOON...]

Find nearby postal boundaries within a radius.

Parameters:

• latitude (required): Center latitude
• longitude (required): Center longitude
• radius_km (optional): Search radius in km (default: 5.0, max: 100)
• limit (optional): Max results (default: 10, max: 50)

validate_digipin

Validate DigiPin format and check if it's a real location.

Parameters:

• digipin (required): DigiPin code to validate

get_usage

Get API usage statistics and quota information.

get_location_statistics

Get live statistics about the Location Lookup service.

get_health

Check API health status.

REST API Wrapper

This project includes a REST API wrapper that makes all MCP tools accessible via HTTP endpoints for mobile and web applications.

Features

• ✅ RESTful API: All MCP tools exposed as HTTP endpoints
• ✅ Authentication: API key via header or environment variable
• ✅ CORS Support: Ready for web and mobile apps
• ✅ Vercel Ready: Optimized for serverless deployment
• ✅ Error Handling: Comprehensive error handling and validation

Quick Start

The REST API is already deployed and ready to use at:

Base URL: https://mcp-gc.quantaroute.com/api

Note: mcp-gc stands for MCP Geocoding. This follows the naming convention:

• mcp-gc.quantaroute.com - Geocoding MCP Server (this project)

Using the REST API

1. Get API Information:

curl https://mcp-gc.quantaroute.com/api

2. Geocode an Address:

curl -X POST https://mcp-gc.quantaroute.com/api/geocode \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "address": "Rohra Address, New Town",
    "city": "New Town",
    "state": "West Bengal",
    "pincode": "700163"
  }'

3. Health Check:

curl -X GET https://mcp-gc.quantaroute.com/api/health \
  -H "x-api-key: your-api-key-here"

4. Find Nearby Boundaries:[NOT RELEASED, COMING SOON...]

curl -X POST https://mcp-gc.quantaroute.com/api/find-nearby-boundaries \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "latitude": 28.6139,
    "longitude": 77.2090,
    "radius_km": 5.0,
    "limit": 10
  }'

This endpoint finds nearby postal boundaries within a specified radius. Useful for:

• Finding all pincodes within X km of a location
• Discovering nearby administrative boundaries
• Location-based search and discovery

JavaScript/TypeScript Example

// Geocode an address
const response = await fetch('https://mcp-gc.quantaroute.com/api/geocode', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your-api-key-here'
  },
  body: JSON.stringify({
    address: 'Rohra Address, Action Area I',
    city: 'New Town',
    state: 'West Bengal'
  })
});

const data = await response.json();
console.log(data);

Python Example

import requests

# Geocode an address
response = requests.post(
    'https://mcp-gc.quantaroute.com/api/geocode',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'your-api-key-here'
    },
    json={
        'address': 'Rohra Address, Action Area I, Ghuni',
        'city': 'New Town',
        'state': 'West Bengal'
    }
)

data = response.json()
print(data)

Deploying Your Own Instance

If you want to deploy your own instance:

1. Deploy to Vercel:

   bash

   Copy

   vercel
   

2. Set Environment Variable (optional, for testing):

   bash

   Copy

   vercel env add QUANTAROUTE_API_KEY
   

3. Configure Custom Domain (optional):

   • Add your custom domain in Vercel
   • Configure DNS CNAME record pointing to Vercel
   • Wait for DNS propagation and SSL certificate

API Documentation

For complete REST API documentation, see API.md.

Available Endpoints:

• GET /api - API information
• GET /api/health - Health check
• GET /api/usage - Usage statistics
• GET /api/location-statistics - Location service statistics
• GET /api/autocomplete?q=query - Address autocomplete
• GET /api/validate-digipin?digipin=XXX-XXX-XXXX - Validate DigiPin
• POST /api/geocode - Geocode an address
• POST /api/reverse-geocode - Reverse geocode DigiPin
• POST /api/coordinates-to-digipin - Convert coordinates to DigiPin
• POST /api/batch-geocode - Batch geocode addresses
• POST /api/lookup-location-from-coordinates - Lookup from coordinates
• POST /api/lookup-location-from-digipin - Lookup from DigiPin
• POST /api/batch-location-lookup - Batch location lookup
• POST /api/find-nearby-boundaries - Find nearby boundaries [COMING SOON...]

Authentication

The API supports authentication in two ways:

1. Request Header (Recommended for production):

   Code

   Copy

   x-api-key: your-api-key-here
   

   • Users should get their own API key from developers.quantaroute.com
   • Send the API key in the x-api-key header with each request
   • Each user's API key is validated by the backend API and usage is tracked separately

2. Environment Variable (Optional fallback for testing):

   Code

   Copy

   QUANTAROUTE_API_KEY=your-api-key-here
   

   • Only used if no x-api-key header is provided
   • Useful for testing and development
   • Not recommended for production use

Priority: The request header takes precedence over the environment variable.