اجرای سرور MCP نشان روی سیستم یا سرور خودتان

اگر به‌جای سرور آماده‌ی نشان ترجیح می‌دهید سرور MCP را خودتان اجرا کنید، این راهنما را دنبال کنید. در این روش سرور روی سیستم یا زیرساخت شما اجرا می‌شود و هر سرویس با کلید و تعرفه‌ی فعلی خودش فراخوانی می‌شود.

پیش‌نیازها

1. Python 3.10 یا بالاتر.
2. کلید API نشان: در پلتفرم نشان ثبت‌نام کنید و کلید سرویس‌های مورد نظر خود را بگیرید.
3. یک کلاینت MCP: Claude Desktop، Cursor یا هر کلاینت دیگری که از MCP پشتیبانی می‌کند.

نصب

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

git clone https://github.com/NeshanMaps/Neshan-MCP.git
cd Neshan-MCP
pip install -e .

تنظیم کلید API

یکی از سه روش زیر را انتخاب کنید:

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

مقدار NESHAN_API_KEY را در بخش env تنظیمات کلاینت بگذارید. نمونه‌ی کامل در صفحه‌ی اتصال کلاینت‌ها آمده است.

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

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

یادداشت

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

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

اگر سرور را در حالت HTTP اجرا کنید، کلید را می‌توانید در هر اتصال جداگانه بفرستید و به فایل env نیازی نیست. نام هدرها در صفحه‌ی اتصال کلاینت‌ها آمده است.

اجرا

سرور دو حالت اجرا دارد:

stdio (پیش‌فرض)

neshan-mcp

حالت پیش‌فرض، برای Claude Desktop و Cursor. معمولاً لازم نیست این دستور را دستی اجرا کنید؛ کلاینت خودش آن را اجرا می‌کند.

HTTP

neshan-mcp-http

سرور روی پورت 3000 در دسترس قرار می‌گیرد و کلاینت به آدرس http://localhost:3000/mcp وصل می‌شود.

Docker

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

ایمیج Docker سرور را در حالت HTTP و روی پورت 3000 اجرا می‌کند.

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

متغیرهای محیطی

همه‌ی متغیرها اختیاری هستند، به‌جز اینکه دست‌کم یک کلید (از متغیر محیطی یا هدر درخواست) باید در دسترس باشد. نمونه‌ی این فایل در .env.example مخزن آمده است.

متغیر	توضیحات	مقدار پیش‌فرض
NESHAN_API_KEY	کلید پیش‌فرض، برای همه‌ی سرویس‌هایی که کلید جداگانه ندارند.	—
NESHAN_KEY_<SERVICE>	کلید اختصاصی یک سرویس، مثلاً NESHAN_KEY_STATIC. جدول کامل در ادامه آمده است.	—
NESHAN_TRANSPORT	حالت اجرا: stdio یا http.	stdio
NESHAN_HOST	آدرسی که سرور HTTP روی آن گوش می‌دهد.	127.0.0.1
NESHAN_PORT	پورت سرور HTTP.	3000
NESHAN_TIMEOUT	مهلت هر درخواست به سرویس‌های نشان، برحسب ثانیه.	15
NESHAN_MAX_RETRIES	تعداد تلاش دوباره برای درخواست‌های ناموفق.	2
NESHAN_LOG_LEVEL	سطح لاگ‌ها.	INFO
NESHAN_BASE_URL	آدرس پایه‌ی سرویس‌های نشان.	https://api.neshan.org
NESHAN_MAP_MATCHING_PATH	مسیر سرویس تطبیق نقشه.	/v3/map-matching
NESHAN_MAP_OUTPUT_DIR	پوشه‌ای که ابزار neshan_map_view فایل HTML نقشه‌ی تعاملی را در آن ذخیره می‌کند.	پوشه‌ی موقت سیستم

کلید اختصاصی هر سرویس

کلیدهای نشان برای هر سرویس جداگانه صادر می‌شوند. اگر برای سرویس‌های مختلف کلید متفاوت دارید، متغیر همان سرویس را مقدار بدهید؛ در غیر این صورت NESHAN_API_KEY استفاده می‌شود.

متغیر	سرویس	ابزارهای مرتبط
NESHAN_KEY_SEARCH	جستجو و تبدیل مختصات به آدرس	neshan_search، neshan_reverse_geocode
NESHAN_KEY_GEOCODING	تبدیل آدرس به مختصات	neshan_geocode، neshan_geocode_plus
NESHAN_KEY_ROUTING	مسیریابی (با ترافیک، بدون ترافیک و الگوی معمول)	neshan_direction
NESHAN_KEY_HISTORICAL	مسیریابی پیش‌بینی	neshan_direction با traffic_mode برابر historical
NESHAN_KEY_MATRIX	ماتریس فاصله	neshan_distance_matrix
NESHAN_KEY_TSP	مسیر چندتوقفه (TSP)	neshan_tsp
NESHAN_KEY_STATIC	نقشه‌ی استاتیک	neshan_static_map
NESHAN_KEY_STATIC_ARC	نقشه‌ی استاتیک با کمان	neshan_static_map_arc
NESHAN_KEY_ISOCHRONE	ایزوکرون	neshan_isochrone
NESHAN_KEY_MAP_MATCHING	تطبیق نقشه	neshan_map_matching
NESHAN_KEY_TRAFFIC	تحلیل ترافیک	neshan_traffic_analytics
NESHAN_KEY_VRP	مسیریابی ناوگان (VRP)	neshan_vrp_logistic
NESHAN_KEY_POINT	اطلاعات مکان‌های شاخص	neshan_get_point_by_hash

اطلاع

کلید هر سرویس را از پنل کاربری نشان بگیرید. اگر در پنل برای کلید محدودیت IP یا دامنه گذاشته‌اید، آدرس سروری که MCP روی آن اجرا می‌شود را هم مجاز کنید.