Skip to main content
Glama
Neshan MCP Server

Neshan MCP Server

Official
by NeshanMaps

Neshan MCP Server

با این پروژه، دستیارهای هوش مصنوعی مثل Claude Desktop یا Cursor به قابلیت‌های نقشه نشان دسترسی پیدا می‌کنند — یعنی می‌توانی مستقیم در چت با آن‌ها بگویی «مسیر خونه تا محل کارم رو با ترافیک الان نشونم بده» یا «نزدیک‌ترین کافه به این مختصات کجاست؟» و جواب را همان‌جا ببینی.

این پروژه یک MCP Server است: یک واسط استاندارد که سرویس‌های نشان را به شکلی در اختیار دستیار هوش مصنوعی می‌گذارد که خودش بتواند در لحظه تصمیم بگیرد از کدام‌شان استفاده کند.

چه کارهایی می‌توان با آن انجام داد؟

بعد از وصل کردن این سرور به دستیار خودت، می‌توانی به زبان معمولی از او بخواهی:

  • جستجوی مکان — پیدا کردن آدرس، کسب‌وکار یا نقطه‌ی موردنظر با اسم یا توضیح

  • تبدیل آدرس ↔ مختصات — گرفتن آدرس از روی مختصات جغرافیایی یا برعکس

  • مسیریابی — مسیر بین دو یا چند نقطه برای خودرو، موتور یا پیاده؛ با ترافیک لحظه‌ای، بدون ترافیک، یا بر اساس الگوی معمول/تاریخی

  • بهینه‌سازی مسیر چند ایستگاهی (TSP) — بهترین ترتیب سر زدن به چند مقصد

  • تطبیق مسیر با جاده (Map Matching) — تبدیل یک رشته نقطه GPS خام به مسیر واقعی روی جاده

  • ناحیه دسترس‌پذیری (Isochrone) — مشخص کردن محدوده‌ای که در زمان/فاصله مشخص از یک نقطه قابل دسترسی است

  • ماتریس فاصله/زمان — فاصله و زمان سفر بین چند مبدا و مقصد به‌صورت هم‌زمان

  • مسیریابی ناوگان (VRP) — تخصیص بهینه‌ی سفارش‌ها به چند وسیله نقلیه با در نظر گرفتن ظرفیت و بازه زمانی

  • نقشه استاتیک — گرفتن یک تصویر نقشه از یک نقطه، یا نقشه‌ای با کمانی بین مبدا و مقصد

  • نقشه تعاملی — ساخت یک صفحه نقشه با نشانگر و مسیر، قابل باز کردن در مرورگر

  • تحلیل ترافیک — وضعیت ترافیک یک منطقه در ۲۴ ساعت گذشته

  • جزئیات یک مکان — گرفتن اطلاعات کامل یک نتیجه جستجو (آدرس، دسته‌بندی، محله)

همه‌ی این‌ها از طریق مکالمه‌ی طبیعی با دستیار اتفاق می‌افتد؛ خودت لازم نیست چیزی درباره‌ی API یا اندپوینت‌ها بدانی.

Related MCP server: Magic Lane MCP Server

سریع‌ترین راه: استفاده از سرور آماده

نیازی به نصب یا اجرای چیزی نیست — کافی است این را به تنظیمات کلاینت خودت (Claude Desktop، Cursor و…) اضافه کنی:

{
    "mcpServers": {
        "neshan": {
            "url": "https://api.neshan.org/mcp",
            "headers": {
                "Api-Key": "YOUR_API_KEY"
            }
        }
    }
}

برای دریافت کلید API، در پنل نشان یک تیکت ثبت کن تا برایت کلید (با دسترسی به سرویس MCP) بسازیم. بعد از دریافت کلید، آن را جایگزین YOUR_API_KEY کن. همین — دستیارت الان به قابلیت‌های نقشه‌ی نشان دسترسی دارد.

اگر ترجیح می‌دهی سرور را خودت روی سیستم/سرور خودت اجرا کنی، ادامه‌ی این راهنما را دنبال کن.

چیزهایی که لازم داری (برای اجرای خودت)

  1. Python 3.10 یا بالاتر

  2. کلید API نشان — از platform.neshan.org ثبت‌نام کن و کلید سرویس(های) موردنظرت را بگیر (رایگان برای شروع)

  3. یکی از این کلاینت‌ها: Claude Desktop، Cursor، یا هر کلاینت دیگری که از MCP پشتیبانی می‌کند

نصب

ابتدا مخزن را کلون کن و داخل پوشه‌ی پروژه، پکیج را نصب کن:

git clone <آدرس-مخزن>
cd Neshan-MCP
pip install -e .

گرفتن و تنظیم کلید API

برای دریافت کلید، در پنل نشان یک تیکت ثبت کن تا برایت کلید بسازیم. سپس یکی از روش‌های زیر را انتخاب کن:

روش ۱ — متغیر محیطی در تنظیمات کلاینت (توصیه‌شده برای Claude Desktop):

مقدار NESHAN_API_KEY را در بخش env تنظیمات کلاینت بگذار (بخش «اتصال به Claude Desktop» را ببین).

روش ۲ — فایل env (برای اجرا در ترمینال یا Docker):

cp .env.example .env
# داخل فایل .env مقدار NESHAN_API_KEY را با کلید خودت جایگزین کن

فایل .env از پوشه‌ای خوانده می‌شود که سرور از آن اجرا می‌شود، پس برای کلاینت‌های دسکتاپ روش ۱ مطمئن‌تر است.

روش ۳ — ارسال کلید در هدر درخواست (برای حالت HTTP):

اگر سرور را به‌صورت HTTP اجرا می‌کنی، می‌توانی کلید را در هر اتصال جداگانه بفرستی و نیازی به فایل env نیست (بخش «اتصال کلاینت» را ببین).

اجرا

neshan-mcp          # حالت stdio (پیش‌فرض)، برای Claude Desktop / Cursor
neshan-mcp-http     # حالت HTTP، روی پورت 3000

یا با Docker (حالت HTTP):

docker build -t neshan-mcp .
docker run -p 3000:3000 --env-file .env neshan-mcp

در حالت HTTP می‌توانی کلید را به‌جای .env در هدر هر درخواست بفرستی.

اتصال به Claude Desktop

فایل تنظیمات Claude Desktop را باز کن و این را اضافه کن:

{
  "mcpServers": {
    "neshan": {
      "command": "neshan-mcp",
      "env": { "NESHAN_API_KEY": "کلید_شما_اینجا" }
    }
  }
}

Claude Desktop را ری‌استارت کن — از این به بعد می‌توانی مستقیم درباره‌ی نقشه، مسیر و آدرس از آن بپرسی.

اتصال از طریق HTTP (Cursor یا کلاینت‌های دیگر)

اگر سرور را با neshan-mcp-http اجرا کرده‌ای:

{
  "mcpServers": {
    "neshan": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": { "Neshan-Api-Key": "کلید_شما_اینجا" }
    }
  }
}

سوالات متداول

آیا کلید API رایگان است؟ نشان یک پلن رایگان برای شروع دارد؛ برای مصرف بیشتر باید طبق پلن‌های platform.neshan.org ارتقا بدهی.

می‌توانم فقط بخشی از سرویس‌ها را فعال کنم؟ بله — برای هر سرویس (جستجو، مسیریابی، نقشه استاتیک و…) می‌توانی کلید جدا بگیری و جدا تنظیم کنی؛ کافی است مقدار NESHAN_KEY_<SERVICE> را در .env (یا در env تنظیمات کلاینت) ست کنی (مثلاً NESHAN_KEY_STATIC).

خطای مربوط به کلید می‌گیرم، چه کار کنم؟ مطمئن شو کلید درست کپی شده و کلید به سرویس موردنظر (و برای سرور آماده، به سرویس MCP) دسترسی داشته باشد و در پنل نشان برای IP/دامنه‌ای که از آن درخواست می‌زنی محدودیتی نگذاشته باشی. اگر مشکل ادامه داشت، یک تیکت در پنل ثبت کن.

مستندات و پشتیبانی

Available Tools

16 tools
neshan_directionA

Calculate a route between two points, choosing how traffic is modeled.

Inputs: dest_lat (required), dest_lng (required), origin_lat (required), origin_lng (required), +9 more.

neshan_distance_matrixB

Compute travel distance and duration for every origin-destination pair.

Inputs: origins (required), destinations (required).

neshan_geocodeA

Convert a free-text Persian address into geographic coordinates.

Cheaper than neshan_geocode_plus — prefer this by default. Switch to neshan_geocode_plus only when the address includes a plaque (پلاک) number or refers to a point of interest by name, which this endpoint does not resolve.

Inputs: address (required).

neshan_geocode_plusA

Geocode an address that includes a plaque (پلاک) number or a named point of interest — neshan_geocode can't resolve those.

More expensive than neshan_geocode, so only use this when plaque/POI resolution is actually needed. Whenever available, pass city, province, a bias location, and/or a bounding box: all of them improve geocoding accuracy regardless of whether plaque/POI resolution is involved.

Inputs: address (required), city, ne_lat, ne_lng, +5 more.

neshan_get_point_by_hashA

Fetch full details of a place using its poiHash from neshan_search results.

Only works for items where neshan_search marked 'verified_details_available: true' (owner-claimed places). This call is expensive — use it selectively for specific candidates you need confirmed details on (precise address, category, working hours, region), not as a blanket follow-up for every search result.

Inputs: hash (required).

neshan_isochroneA

Calculate the reachable area from a point within a given time or distance (isochrone).

Returns a GeoJSON FeatureCollection. Each feature's geometry is a Polygon or LineString (controlled by 'polygon') and properties.metric is 'time' or 'distance'. Both distance and time can be requested simultaneously.

Inputs: lat (required), lng (required), time, denoise, +2 more.

neshan_map_matchingC

Snap a sequence of GPS points onto the road network (map matching).

Inputs: path_points (required).

neshan_map_viewA

Generate an interactive Neshan map HTML file and save it locally.

Creates a fully interactive map page using the Neshan Maps SDK. Supports markers with popups and route polylines drawn on the map. The map auto-fits to show all markers and routes. Open the returned file_path in any browser to view the map.

Inputs: zoom, title, routes, map_key, +5 more.

neshan_reverse_geocodeA

Convert coordinates into a human-readable Persian address.

Inputs: lat (required), lng (required).

neshan_static_mapC

Render a static map image (PNG) centered on a coordinate.

Inputs: lat (required), lng (required), zoom, width, +3 more.

neshan_static_map_arcA

Render a static map image (PNG) with a curved arc line between two points.

Useful for visualising geographic connections, travel reports, or origin-destination relationships on a map without performing full routing.

Inputs: dest_lat (required), dest_lng (required), origin_lat (required), origin_lng (required), +7 more.

neshan_traffic_analyticsA

Analyse historical traffic patterns around a location.

Returns three things:

  • kpi: overall traffic congestion score for the location (higher = more congested).

  • chart: 24-hour traffic breakdown — one entry per hour with a numeric score and a color key (green → free flow, yellow → moderate, orange → heavy, red → congested).

  • static_map: a PNG image of the area (~500 m radius) with traffic overlay.

Inputs: lat (required), lng (required).

neshan_tspB

Find the optimal visiting order for multiple destinations (TSP).

Inputs: waypoints (required), round_trip, last_is_any_point, source_is_any_point.

neshan_vrp_logisticB

Solve a Vehicle Routing Problem (VRP) for logistics / delivery optimization.

Assigns a set of jobs to vehicles starting from a depot, minimising total distance or duration, respecting vehicle capacities, skills, and time windows. See each object's field descriptions in the tool schema for exact shape.

Inputs: jobs (required), depot (required), vehicles (required), cost_type, +7 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 16 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: geocoding (with two variants clearly differentiated), routing, distance matrix, isochrones, map matching, search, reverse geocoding, static maps (standard and arc), traffic analytics, deeplinks, TSP, and VRP. No two tools overlap, and descriptions provide explicit guidance on when to use each.

    Naming Consistency5/5

    All tool names follow a consistent 'neshan_' prefix followed by a descriptive snake_case name (e.g., 'neshan_direction', 'neshan_geocode_plus', 'neshan_vrp_logistic'). The naming pattern is uniform and predictable across all 16 tools.

    Tool Count5/5

    With 16 tools covering geocoding, routing, search, static maps, traffic, optimization, and more, the count is well-scoped for a comprehensive mapping server. Each tool serves a distinct function without redundancy or excessive granularity.

    Completeness5/5

    The tool surface is remarkably complete for a mapping API server. It includes forward/reverse geocoding, routing, distance matrix, isochrones, map matching, search, static maps (with arc variant), traffic analytics, deeplinks, interactive map view, TSP, and VRP. No obvious gaps for core mapping workflows.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers