io.github.mapdevsaikat/quantaroute-geocoder

Geocode addresses, lookup administrative boundaries, and process DigiPin codes for India

Open source Open in the app JSON README (API)

About

Geocode addresses, lookup administrative boundaries, and process DigiPin codes for India

Details

Kind

MCP servers

Topic

No topic detected

Publisher

mapdevsaikat

Origin

official

Category

ferramentas

Transport

local

Version

1.0.0

Forks

1

Last push

2026-02-12T18:30:56Z

Repository state

ativo

Language

TypeScript

License

MIT

Added

2026-08-29 04:00:27

Updated

2026-08-29 04:00:27

Origin id

io.github.mapdevsaikat/quantaroute-geocoder

README

# 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`](https://www.npmjs.com/package/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:

```json
{
  "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`):

```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:**
```json
{
  "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:**
```bash
curl https://mcp-gc.quantaroute.com/api
```

**2. Geocode an Address:**
```bash
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:**
```bash
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...]**
```bash
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

```javascript
// 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

```python
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
   vercel
   ```

2. **Set Environment Variable** (optional, for testing):
   ```bash
   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](./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):
   ```
   x-api-key: your-api-key-here
   ```
   - Users should get their own API key from [developers.quantaroute.com](https://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):
   ```
   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.

**Getting an API Key**: 
- Visit [developers.quantaroute.com](https://developers.quantaroute.com)
- Sign up and get your API key
- Use it in the `x-api-key` header for all API requests

## Development

### Prerequisites
- Node.js 18+
- TypeScript 5+

### Setup

```bash
# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev
```

### Project Structure

```
mcp-server/
├── src/
│   ├── index.ts          # Main MCP server implementation
│   └── client.ts         # QuantaRoute API client
├── api/
│   └── [...path].ts      # REST API wrapper (Vercel serverless function)
├── dist/                 # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── vercel.json           # Vercel configuration
├── README.md
└── API.md                # REST API documentation
```

## API Documentation

Full API documentation: https://api.quantaroute.com/v1/digipin/docs

## License

MIT License

## Support

- **Website**: https://quantaroute.com
- **API Docs**: https://api.quantaroute.com/v1/digipin/docs
- **Issues**: https://github.com/mapdevsaikat/quantaroute-geocoder/issues

## Supported Platforms

✅ **Claude Desktop** - Fully supported  
✅ **Cursor** - Fully supported  
✅ **Other MCP-compatible clients** - Should work with any MCP-compatible application

## Example Usage in AI Assistants

Once configured, AI assistants (Claude, Cursor AI, etc.) can use tools like:

### Example 1: Geocoding
```
User: "What's the DigiPin for Biswa Bangla Gate, New Town?"

Assistant: [Uses geocode tool]
The DigiPin code for that address is 2TF-39M-JT5F, located at coordinates 22.5788545, 88.4716628.
Full Address: Biswa Bangla Gate, New Town, Biswa Bangla Sarani, Action Area I, New Town, Bidhannagar, North 24 Parganas, West Bengal, 700156, India
```

### Example 2: Location Lookup
```
User: "What administrative boundaries are at coordinates 28.6139, 77.2090?"

Assistant: [Uses lookup_location_from_coordinates tool]
That location is in:
- Pincode: 110001
- State: Delhi
- Division: New Delhi Central
- Locality: Connaught Place
- District: New Delhi
```

### Example 3: Reverse Geocoding
```
User: "What's the address for DigiPin 2TF-3FT-J825?"

Assistant: [Uses reverse_geocode tool]
The DigiPin 2TF-3FT-J825 corresponds to:
- Address: FE Block, Sector III, Bidhannagar, North 24 Parganas, West Bengal, 700106, India
- Coordinates: 22.580587°N, 88.419001°E
```

## Troubleshooting

### Claude Desktop Issues

1. **Server not appearing in Claude Desktop:**
   - Verify the config file path is correct for your OS
   - Check that the JSON syntax is valid
   - Restart Claude Desktop completely

2. **"Command not found" errors:**
   - Ensure Node.js 18+ is installed: `node --version`
   - Verify `npx` is available: `which npx`

3. **API authentication errors:**
   - Check that `QUANTAROUTE_API_KEY` is set correctly in the config
   - Verify the API key is valid at https://api.quantaroute.com

### Cursor Issues

1. **MCP server not loading:**
   - Check `~/.cursor/mcp.json` exists and has valid JSON
   - Restart Cursor completely
   - Check Cursor's MCP logs for errors

2. **Tools not available:**
   - Verify the server is running (check Cursor's MCP status)
   - Ensure API key is configured correctly

More

• More mcp servers on No topic detected
• Everything published by mapdevsaikat
• Browse the whole catalog