{
  "markdown": "# QuantaRoute MCP Server\n\nA 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.\n\n**Package**: `@quantaroute/mcp-server` (MCP Server for AI Agents)  \n**SDK**: [`quantaroute-geocoding`](https://www.npmjs.com/package/quantaroute-geocoding) (Node.js/TypeScript SDK)\n\n**✅ Fully compatible with Claude Desktop and Cursor**\n\n## Features\n\n### 🗺️ Geocoding Tools\n- **Geocode addresses** to DigiPin codes and coordinates\n- **Reverse geocode** DigiPin codes to addresses\n- **Convert coordinates** to DigiPin codes\n- **Validate DigiPin** format and location\n- **Batch geocode** multiple addresses (up to 100)\n- **Autocomplete** address suggestions\n\n### 🚀 Revolutionary Location Lookup with Nominatim + Pincode + Digipin\n- **Lookup administrative boundaries** from coordinates (pincode, state, division, locality)\n- **Lookup from DigiPin** codes\n- **Batch location lookup** for multiple locations\n- **Find nearby boundaries** within a radius [COMING SOON...]\n- Access to **36,000+ postal boundaries** across India\n\n### 📊 Utility Tools\n- **Get API usage** statistics\n- **Get location statistics** (boundaries, states, divisions)\n- **Check API health** status\n\n## Installation\n\nThis MCP server is compatible with **Claude Desktop** and **Cursor**. Follow the instructions below for your platform.\n\n### For Claude Desktop\n\n1. **Locate the Claude Desktop configuration file:**\n   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n   - **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n2. **Edit the configuration file** and add:\n\n```json\n{\n  \"mcpServers\": {\n    \"quantaroute\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@quantaroute/mcp-server\"\n      ],\n      \"env\": {\n        \"QUANTAROUTE_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n3. **Save and restart Claude Desktop** to apply the changes.\n\n### For Cursor\n\nAdd to your MCP configuration file (`~/.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"quantaroute\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@quantaroute/mcp-server\"\n      ],\n      \"env\": {\n        \"QUANTAROUTE_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\nRestart Cursor after making changes.\n\n### Environment Variables\n\n- `QUANTAROUTE_API_KEY` (required): Your QuantaRoute API key\n  - Get your API key from: https://developers.quantaroute.com\n  - Free tier test key: `demo_free_key_123` (for testing)\n\n## Available Tools\n\n### `geocode`\nGeocode an address to get DigiPin code and coordinates.\n\n**Parameters:**\n- `address` (required): The address to geocode\n- `city` (optional): City name\n- `state` (optional): State name\n- `pincode` (optional): Postal code\n- `country` (optional): Country name (defaults to India)\n\n**Example:**\n```json\n{\n  \"address\": \"Rohra Address, New Town\",\n  \"city\": \"New Town\",\n  \"state\": \"West Bengal\",\n  \"pincode\": \"700163\"\n}\n```\n\n### `reverse_geocode`\nReverse geocode a DigiPin code to get coordinates and address.\n\n**Parameters:**\n- `digipin` (required): DigiPin code (format: XXX-XXX-XXXX)\n\n### `coordinates_to_digipin`\nConvert latitude and longitude to DigiPin code.\n\n**Parameters:**\n- `latitude` (required): Latitude (-90 to 90)\n- `longitude` (required): Longitude (-180 to 180)\n\n### `lookup_location_from_coordinates`\n🚀 **REVOLUTIONARY**: Get administrative boundaries from coordinates.\n\nReturns: pincode, state, division, locality, district, population density, and more.\n\n**Parameters:**\n- `latitude` (required): Latitude coordinate\n- `longitude` (required): Longitude coordinate\n\n### `lookup_location_from_digipin`\nGet administrative boundaries from a DigiPin code.\n\n**Parameters:**\n- `digipin` (required): DigiPin code\n\n### `batch_location_lookup`\nBatch lookup for multiple locations (up to 100).\n\n**Parameters:**\n- `locations` (required): Array of location objects\n  - Each object can have `latitude` + `longitude` OR `digipin`\n\n### `batch_geocode`\nGeocode multiple addresses in a single request (up to 100).\n\n**Parameters:**\n- `addresses` (required): Array of address objects\n\n### `autocomplete`\nGet address autocomplete suggestions.\n\n**Parameters:**\n- `query` (required): Search query (minimum 3 characters)\n- `limit` (optional): Max suggestions (default: 5, max: 10)\n\n### `find_nearby_boundaries [COMING SOON...]`\nFind nearby postal boundaries within a radius.\n\n**Parameters:**\n- `latitude` (required): Center latitude\n- `longitude` (required): Center longitude\n- `radius_km` (optional): Search radius in km (default: 5.0, max: 100)\n- `limit` (optional): Max results (default: 10, max: 50)\n\n### `validate_digipin`\nValidate DigiPin format and check if it's a real location.\n\n**Parameters:**\n- `digipin` (required): DigiPin code to validate\n\n### `get_usage`\nGet API usage statistics and quota information.\n\n### `get_location_statistics`\nGet live statistics about the Location Lookup service.\n\n### `get_health`\nCheck API health status.\n\n## REST API Wrapper\n\nThis project includes a REST API wrapper that makes all MCP tools accessible via HTTP endpoints for mobile and web applications.\n\n### Features\n\n- ✅ **RESTful API**: All MCP tools exposed as HTTP endpoints\n- ✅ **Authentication**: API key via header or environment variable\n- ✅ **CORS Support**: Ready for web and mobile apps\n- ✅ **Vercel Ready**: Optimized for serverless deployment\n- ✅ **Error Handling**: Comprehensive error handling and validation\n\n### Quick Start\n\nThe REST API is **already deployed** and ready to use at:\n\n**Base URL**: `https://mcp-gc.quantaroute.com/api`\n\n**Note**: `mcp-gc` stands for MCP Geocoding. This follows the naming convention:\n- `mcp-gc.quantaroute.com` - Geocoding MCP Server (this project)\n\n#### Using the REST API\n\n**1. Get API Information:**\n```bash\ncurl https://mcp-gc.quantaroute.com/api\n```\n\n**2. Geocode an Address:**\n```bash\ncurl -X POST https://mcp-gc.quantaroute.com/api/geocode \\\n  -H \"Content-Type: application/json\" \\\n  -H \"x-api-key: your-api-key-here\" \\\n  -d '{\n    \"address\": \"Rohra Address, New Town\",\n    \"city\": \"New Town\",\n    \"state\": \"West Bengal\",\n    \"pincode\": \"700163\"\n  }'\n```\n\n**3. Health Check:**\n```bash\ncurl -X GET https://mcp-gc.quantaroute.com/api/health \\\n  -H \"x-api-key: your-api-key-here\"\n```\n\n**4. Find Nearby Boundaries:[NOT RELEASED, COMING SOON...]**\n```bash\ncurl -X POST https://mcp-gc.quantaroute.com/api/find-nearby-boundaries \\\n  -H \"Content-Type: application/json\" \\\n  -H \"x-api-key: your-api-key-here\" \\\n  -d '{\n    \"latitude\": 28.6139,\n    \"longitude\": 77.2090,\n    \"radius_km\": 5.0,\n    \"limit\": 10\n  }'\n```\n\nThis endpoint finds nearby postal boundaries within a specified radius. Useful for:\n- Finding all pincodes within X km of a location\n- Discovering nearby administrative boundaries\n- Location-based search and discovery\n\n#### JavaScript/TypeScript Example\n\n```javascript\n// Geocode an address\nconst response = await fetch('https://mcp-gc.quantaroute.com/api/geocode', {\n  method: 'POST',\n  headers: {\n    'Content-Type': 'application/json',\n    'x-api-key': 'your-api-key-here'\n  },\n  body: JSON.stringify({\n    address: 'Rohra Address, Action Area I',\n    city: 'New Town',\n    state: 'West Bengal'\n  })\n});\n\nconst data = await response.json();\nconsole.log(data);\n```\n\n#### Python Example\n\n```python\nimport requests\n\n# Geocode an address\nresponse = requests.post(\n    'https://mcp-gc.quantaroute.com/api/geocode',\n    headers={\n        'Content-Type': 'application/json',\n        'x-api-key': 'your-api-key-here'\n    },\n    json={\n        'address': 'Rohra Address, Action Area I, Ghuni',\n        'city': 'New Town',\n        'state': 'West Bengal'\n    }\n)\n\ndata = response.json()\nprint(data)\n```\n\n#### Deploying Your Own Instance\n\nIf you want to deploy your own instance:\n\n1. **Deploy to Vercel**:\n   ```bash\n   vercel\n   ```\n\n2. **Set Environment Variable** (optional, for testing):\n   ```bash\n   vercel env add QUANTAROUTE_API_KEY\n   ```\n\n3. **Configure Custom Domain** (optional):\n   - Add your custom domain in Vercel\n   - Configure DNS CNAME record pointing to Vercel\n   - Wait for DNS propagation and SSL certificate\n\n### API Documentation\n\nFor complete REST API documentation, see [API.md](./API.md).\n\n**Available Endpoints:**\n- `GET /api` - API information\n- `GET /api/health` - Health check\n- `GET /api/usage` - Usage statistics\n- `GET /api/location-statistics` - Location service statistics\n- `GET /api/autocomplete?q=query` - Address autocomplete\n- `GET /api/validate-digipin?digipin=XXX-XXX-XXXX` - Validate DigiPin\n- `POST /api/geocode` - Geocode an address\n- `POST /api/reverse-geocode` - Reverse geocode DigiPin\n- `POST /api/coordinates-to-digipin` - Convert coordinates to DigiPin\n- `POST /api/batch-geocode` - Batch geocode addresses\n- `POST /api/lookup-location-from-coordinates` - Lookup from coordinates\n- `POST /api/lookup-location-from-digipin` - Lookup from DigiPin\n- `POST /api/batch-location-lookup` - Batch location lookup\n- `POST /api/find-nearby-boundaries` - Find nearby boundaries [COMING SOON...]\n\n### Authentication\n\nThe API supports authentication in two ways:\n\n1. **Request Header** (Recommended for production):\n   ```\n   x-api-key: your-api-key-here\n   ```\n   - Users should get their own API key from [developers.quantaroute.com](https://developers.quantaroute.com)\n   - Send the API key in the `x-api-key` header with each request\n   - Each user's API key is validated by the backend API and usage is tracked separately\n\n2. **Environment Variable** (Optional fallback for testing):\n   ```\n   QUANTAROUTE_API_KEY=your-api-key-here\n   ```\n   - Only used if no `x-api-key` header is provided\n   - Useful for testing and development\n   - Not recommended for production use\n\n**Priority**: The request header takes precedence over the environment variable.\n\n**Getting an API Key**: \n- Visit [developers.quantaroute.com](https://developers.quantaroute.com)\n- Sign up and get your API key\n- Use it in the `x-api-key` header for all API requests\n\n## Development\n\n### Prerequisites\n- Node.js 18+\n- TypeScript 5+\n\n### Setup\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Run in development mode\nnpm run dev\n```\n\n### Project Structure\n\n```\nmcp-server/\n├── src/\n│   ├── index.ts          # Main MCP server implementation\n│   └── client.ts         # QuantaRoute API client\n├── api/\n│   └── [...path].ts      # REST API wrapper (Vercel serverless function)\n├── dist/                 # Compiled JavaScript (generated)\n├── package.json\n├── tsconfig.json\n├── vercel.json           # Vercel configuration\n├── README.md\n└── API.md                # REST API documentation\n```\n\n## API Documentation\n\nFull API documentation: https://api.quantaroute.com/v1/digipin/docs\n\n## License\n\nMIT License\n\n## Support\n\n- **Website**: https://quantaroute.com\n- **API Docs**: https://api.quantaroute.com/v1/digipin/docs\n- **Issues**: https://github.com/mapdevsaikat/quantaroute-geocoder/issues\n\n## Supported Platforms\n\n✅ **Claude Desktop** - Fully supported  \n✅ **Cursor** - Fully supported  \n✅ **Other MCP-compatible clients** - Should work with any MCP-compatible application\n\n## Example Usage in AI Assistants\n\nOnce configured, AI assistants (Claude, Cursor AI, etc.) can use tools like:\n\n### Example 1: Geocoding\n```\nUser: \"What's the DigiPin for Biswa Bangla Gate, New Town?\"\n\nAssistant: [Uses geocode tool]\nThe DigiPin code for that address is 2TF-39M-JT5F, located at coordinates 22.5788545, 88.4716628.\nFull Address: Biswa Bangla Gate, New Town, Biswa Bangla Sarani, Action Area I, New Town, Bidhannagar, North 24 Parganas, West Bengal, 700156, India\n```\n\n### Example 2: Location Lookup\n```\nUser: \"What administrative boundaries are at coordinates 28.6139, 77.2090?\"\n\nAssistant: [Uses lookup_location_from_coordinates tool]\nThat location is in:\n- Pincode: 110001\n- State: Delhi\n- Division: New Delhi Central\n- Locality: Connaught Place\n- District: New Delhi\n```\n\n### Example 3: Reverse Geocoding\n```\nUser: \"What's the address for DigiPin 2TF-3FT-J825?\"\n\nAssistant: [Uses reverse_geocode tool]\nThe DigiPin 2TF-3FT-J825 corresponds to:\n- Address: FE Block, Sector III, Bidhannagar, North 24 Parganas, West Bengal, 700106, India\n- Coordinates: 22.580587°N, 88.419001°E\n```\n\n## Troubleshooting\n\n### Claude Desktop Issues\n\n1. **Server not appearing in Claude Desktop:**\n   - Verify the config file path is correct for your OS\n   - Check that the JSON syntax is valid\n   - Restart Claude Desktop completely\n\n2. **\"Command not found\" errors:**\n   - Ensure Node.js 18+ is installed: `node --version`\n   - Verify `npx` is available: `which npx`\n\n3. **API authentication errors:**\n   - Check that `QUANTAROUTE_API_KEY` is set correctly in the config\n   - Verify the API key is valid at https://api.quantaroute.com\n\n### Cursor Issues\n\n1. **MCP server not loading:**\n   - Check `~/.cursor/mcp.json` exists and has valid JSON\n   - Restart Cursor completely\n   - Check Cursor's MCP logs for errors\n\n2. **Tools not available:**\n   - Verify the server is running (check Cursor's MCP status)\n   - Ensure API key is configured correctly\n\n",
  "bytes": 13184,
  "sha": "b5242d5c48fc5b75c10229b9cf5bbc5e7fe0314c1ad56b57d165fc7479dbc444",
  "repo_slug": "mapdevsaikat/quantaroute-geocoder",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mapdevsaikat_quantaroute_geoco_9352f23f/readme"
}