Content
# Neshan MCP Server
With this project, AI assistants like **Claude Desktop** or **Cursor** gain access to [Neshan](https://platform.neshan.org) map capabilities — meaning you can directly ask them, for example, *"Show me the route from home to work with current traffic"* or *"What's the nearest cafe to these coordinates?"* and get the answer right away.
This project is an [MCP Server](https://modelcontextprotocol.io): a standard interface that makes Neshan services available to AI assistants in a way that allows them to decide which services to use on the fly.
## What can you do with it?
After connecting this server to your assistant, you can ask it in natural language:
- **Location search** — find an address, business, or point of interest by name or description
- **Address ↔ coordinates conversion** — get an address from geographic coordinates or vice versa
- **Routing** — get the route between two or more points for a car, motorcycle, or pedestrian; with real-time traffic, without traffic, or based on usual/historical patterns
- **Multi-stop route optimization (TSP)** — find the best order to visit multiple destinations
- **Map matching** — convert a raw GPS point string into an actual road route
- **Isochrone** — determine the area that can be reached within a certain time/distance from a point
- **Distance/time matrix** — get the distance and travel time between multiple origins and destinations simultaneously
- **Vehicle routing (VRP)** — optimally assign orders to multiple vehicles considering capacity and time windows
- **Static map** — get a map image from a point or a map with a route between origin and destination
- **Interactive map** — create a map page with markers and routes that can be opened in a browser
- **Traffic analysis** — get the traffic status of an area over the past 24 hours
- **Place details** — get detailed information about a search result (address, category, neighborhood)
All of this happens through natural conversation with your assistant; you don't need to know anything about APIs or endpoints.
## The quickest way: using a ready-made server
No installation or execution required — just add this to your client settings (Claude Desktop, Cursor, etc.):
```json
{
"mcpServers": {
"neshan": {
"type": "http",
"url": "https://platform-stage.rajman.org/mcp",
"headers": { "Neshan-Api-Key": "your_api_key_here" }
}
}
}
```
> Ready-made server address: `https://platform-stage.rajman.org/mcp`
Get your API key from the [Neshan panel](https://platform.neshan.org) (see the "Getting and setting your API key" section). That's it — your assistant now has access to Neshan map capabilities.
If you prefer to run the server yourself, follow the rest of this guide.
## Requirements (for self-execution)
1. **Python 3.10 or higher**
2. **Neshan API key** — sign up at [platform.neshan.org](https://platform.neshan.org) and get a service key (free to start)
3. One of these clients: Claude Desktop, Cursor, or any other MCP-supported client
## Installation
```bash
pip install -e .
```
## Getting and setting your API key
Get your key from the [Neshan panel](https://platform.neshan.org), then choose one of two methods:
**Method 1 — .env file (simplest, recommended for Claude Desktop):**
```bash
cp .env.example .env
# replace NESHAN_API_KEY with your key in the .env file
```
**Method 2 — sending the key in the request header (for HTTP):**
If you run the server as HTTP, you can send the key with each connection separately, and no .env file is needed (see "Connecting the client").
## Execution
```bash
neshan-mcp # default mode, for Claude Desktop / Cursor
```
or with Docker:
```bash
docker build -t neshan-mcp .
docker run -p 3000:3000 --env-file .env neshan-mcp
```
## Connecting to Claude Desktop
Open Claude Desktop settings and add:
```json
{
"mcpServers": {
"neshan": {
"command": "neshan-mcp",
"env": { "NESHAN_API_KEY": "your_api_key_here" }
}
}
}
```
Restart Claude Desktop — from now on, you can ask it about maps, routes, and addresses directly.
## Connecting via HTTP (Cursor or other clients)
If you run the server with `neshan-mcp-http`:
```json
{
"mcpServers": {
"neshan": {
"type": "http",
"url": "http://localhost:3000/mcp",
"headers": { "Neshan-Api-Key": "your_api_key_here" }
}
}
}
```
## Frequently Asked Questions
**Is the API key free?**
Neshan offers a free plan to get started; for more usage, you need to upgrade according to the plans at [platform.neshan.org](https://platform.neshan.org).
**Can I enable only some services?**
Yes — for each service (search, routing, static map, etc.), you can get a separate key and configure it separately; just set `NESHAN_KEY_<SERVICE>` in the `.env` file (e.g., `NESHAN_KEY_STATIC`).
**I get a key-related error, what should I do?**
Make sure you copied the key correctly and didn't set any restrictions on the key in the Neshan panel for your IP/domain.
## Documentation and support
- Full Neshan API documentation: https://platform.neshan.org/docs
