MCP Reference: mapstools.googleapis.com

‫This is an MCP server provided by Maps Experience Agent Tools. این سرور ابزارهایی را برای توسعه‌دهندگان فراهم می‌کند تا برنامه‌های LLM را روی «پلاتفرم Google Maps» بسازند.

سرور «پروتکل بافتار مدل» (MCP) به‌عنوان پراکسی بین یک سرویس خارجی که بافتار، داده، یا قابلیت‌ها را به «مدل زبانی بزرگ» (LLM) یا برنامه هوش مصنوعی ارائه می‌دهد عمل می‌کند. سرورهای MCP برنامه‌های هوش مصنوعی را به سیستم‌های خارجی مانند پایگاه‌های داده و سرویس‌های وب متصل می‌کنند و پاسخ‌های آن‌ها را به قالبی ترجمه می‌کنند که برنامه هوش مصنوعی بتواند درک کند.

راه‌اندازی سرور

باید قبل‌از استفاده، سرورهای MCP را فعال کنید و اصالت‌سنجی را راه‌اندازی کنید. برای اطلاعات بیشتر درباره استفاده از سرورهای MCP راه دور Google و Google Cloud، به نمای کلی سرورهای Google Cloud MCP مراجعه کنید.

نقطه‌های پایانی سرور

نقطه پایان سرویس MCP نشانی شبکه و میانای ارتباطی (معمولاً نشانی وب) سرور MCP است که برنامه هوش مصنوعی (میزبان کارخواه MCP) از آن برای برقراری اتصال ایمن و استاندارد استفاده می‌کند. این نقطه تماس برای LLM است تا بافت را درخواست کند، ابزاری را فراخوانی کند، یا به منبعی دسترسی پیدا کند. نقطه‌های پایانی MCP‏ Google می‌توانند جهانی یا منطقه‌ای باشند.

سرور MCP مربوط به Maps Experience Agent Tools دارای نقطه پایانی MCP جهانی زیر است:

  • https://mapstools.googleapis.com/mcp

ابزارهای «پروتکل زمینه‌ای مدل» (MCP)

ابزار MCP تابع یا قابلیت اجرایی است که سرور MCP برای انجام کنشی در دنیای واقعی دراختیار مدل زبانی بزرگ یا برنامه هوش مصنوعی قرار می‌دهد.

ابزارها

سرور MCP‏ mapstools.googleapis.com ابزارهای زیر را دارد:

ابزارهای «پروتکل زمینه‌ای مدل» (MCP)
search_places

وقتی درخواست کاربر پیدا کردن مکان‌ها، کسب‌وکارها، نشانی‌ها، موقعیت‌ها، نقاط دیدنی، یا هر جستجوی دیگری مرتبط با Google Maps است، این ابزار را فراخوانی کنید.

الزامات ورودی (بسیار مهم):

  1. text_query (رشته - اجباری): پُرسمان جستجوی اصلی. این باید به‌وضوح آنچه را که کاربر به‌دنبال آن است تعریف کند.

    • نمونه‌ها: 'restaurants in New York'، 'coffee shops near Golden Gate Park'، 'SF MoMA'، '1600 Amphitheatre Pkwy, Mountain View, CA, USA'، 'pets friendly parks in Manhattan, New York'، 'date night restaurants in Chicago'، 'accessible public libraries in Los Angeles'.
    • برای جزئیات مکان خاص: مشخصه درخواستی را اضافه کنید (مثلاً 'Google Store Mountain View opening hours'، 'SF MoMa phone number'، 'Shoreline Park Mountain View address').

  2. location_bias (شیء - اختیاری): از این مورد برای اولویت‌بندی نتایج نزدیک به یک منطقه جغرافیایی خاص استفاده کنید.

    • قالب: {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
    • کاربرد:
      • برای سوگیری به شعاع ۵ کیلومتری: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
      • برای سوگیری قوی به نقطه مرکزی: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (radius_meters حذف می‌شود).

  3. ‫language_code (رشته - اختیاری): زبانی که خلاصه نتایج جستجو به آن نشان داده می‌شود.

    • قالب: کد زبان دوحرفی (ISO 639-1)، که به‌صورت اختیاری با زیرخط و کد کشور دوحرفی (ISO 3166-1 alpha-2) دنبال می‌شود، مثلاً en، ja، en_US، zh_CN، es_MX. اگر کد زبان ارائه نشود، نتایج به زبان انگلیسی خواهد بود.

  4. region_code (رشته - اختیاری): کد منطقه CLDR یونی‌کد کاربر. این پارامتر برای نمایش جزئیات مکان، مانند نام مکان خاص منطقه، درصورت وجود، استفاده می‌شود. این پارامتر می‌تواند براساس قانون ذی‌ربط بر نتایج تأثیر بگذارد.

    • قالب: کد کشور دوحرفی (ISO 3166-1 alpha-2)، مثلاً US، CA.

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

  • اطلاعات مکان (بسیار مهم): جستجو باید حاوی اطلاعات مکان کافی باشد. اگر مکان مبهم است (مثلاً فقط «پیتزافروشی»)، باید آن را در text_query مشخص کنید (مثلاً «پیتزافروشی در نیویورک») یا از پارامتر location_bias استفاده کنید. درصورت نیاز برای ابهام‌زدایی، نام شهر، ایالت/ استان، و منطقه/ کشور را اضافه کنید.

  • همیشه دقیق‌ترین و غنی‌ترین text_query ممکن را ازنظر بافت ارائه دهید.

  • فقط زمانی از location_bias استفاده کنید که مختصات به‌طور صریح ارائه شده باشد یا اگر استنباط مکان از بافت شناخته‌شده کاربر مناسب و برای نتایج بهتر ضروری باشد.

  • برونداد مستند باید بااستفاده از اطلاعات فیلد attribution (درصورت وجود) به منبع نسبت داده شود.
lookup_weather

داده‌های جامع آب‌وهوا ازجمله شرایط کنونی، پیش‌بینی‌های ساعتی، و روزانه را بازیابی می‌کند.

داده‌های خاص دردسترس: دما (فعلی، دمای احساسی، حداکثر/حداقل، شاخص گرما)، باد (سرعت، تندباد، جهت)، رویدادهای آسمانی (طلوع/غروب خورشید، فاز ماه)، بارش (نوع، احتمال، مقدار/QPF)، شرایط جوی (شاخص فرابنفش، رطوبت، پوشش ابر، احتمال رعدوبرق)، و نشانی مکان زمین‌کدیابی‌شده.

مکان و قوانین مکان (بسیار مهم):

مکانی که داده‌های آب‌وهوا برای آن درخواست شده است بااستفاده از فیلد location مشخص می‌شود. این فیلد ساختار «oneof» دارد، یعنی برای اطمینان از جستجوی دقیق داده‌های آب‌وهوا، باید فقط برای یکی از سه فیلد فرعی مکان زیر مقدار ارائه دهید.

  1. مختصات جغرافیایی (lat_lng)

    • وقتی مختصات دقیق طول/عرض جغرافیایی به شما ارائه می‌شود، از آن استفاده کنید.
    • مثال: {"location": {"lat_lng": {"latitude": 34.0522, "longitude": -118.2437}}} // Los Angeles

  2. شناسه جا (place_id)

    • شناسه رشته‌ای بدون ابهام (شناسه مکان Google Maps).
    • ‫place_id را می‌توان از ابزار search_places واکشی کرد.
    • مثال: {"location": {"place_id": "ChIJLU7jZClu5kcR4PcOOO6p3I0"}} // برج ایفل

  3. رشته نشانی (نشانی)

    • رشته‌ای با قالب آزاد که برای زمین‌کدیابی به جزئیات نیاز دارد.
    • شهر و منطقه: همیشه منطقه/کشور را اضافه کنید (مثلاً «لندن، پادشاهی متحد»، نه «لندن»).
    • نشانی خیابان: نشانی کامل را ارائه دهید (مثلاً «1600 Pennsylvania Ave NW, Washington, DC»).
    • کد پستی: باید همراه با نام کشور باشد (برای نمونه، «90210, USA» و نه «90210»).
    • مثال: {"location": {"address": "1600 Pennsylvania Ave NW, Washington, DC"}}

حالت‌های استفاده:

  • آب‌وهوای فعلی: فقط location را ارائه دهید. date و hour را مشخص نکنید.

  • پیش‌بینی ساعت‌به‌ساعت: location، date، و hour (۰-۲۳) را ارائه دهید. از آن برای زمان‌های خاص (مثلاً «ساعت ۵ بعدازظهر») یا عباراتی مانند «چند ساعت آینده» یا «اواخر امروز» استفاده کنید. اگر کاربر دقیقه را مشخص کرد، به‌سمت نزدیک‌ترین ساعت گرد کنید. پیش‌بینی ساعت‌به‌ساعت برای بیش‌از ۱۲۰ ساعت آینده پشتیبانی نمی‌شود. آب‌وهوای ساعتی گذشته تا ۲۴ ساعت قبل پشتیبانی می‌شود.

  • پیش‌بینی روزانه: location و date را ارائه می‌دهد. hour را مشخص نکنید. برای درخواست‌های عمومی روزانه استفاده کنید (مثلاً «آب‌وهوای فردا»، «آب‌وهوای جمعه»، «آب‌وهوای ۲۵ دسامبر»). اگر تاریخ امروز در بافتار نیست، باید آن را با کاربر شفاف‌سازی کنید. پیش‌بینی روزانه برای بیش‌از ۱۰ روز ازجمله امروز پشتیبانی نمی‌شود. از آب‌وهوای گذشته پشتیبانی نمی‌شود.

محدودیت‌های پارامتر:

  • مناطق زمانی: همه ورودی‌های date و hour باید نسبت به منطقه زمانی محلی مکان باشند، نه منطقه زمانی کاربر.
  • قالب تاریخ: ورودی‌ها باید به {year, month, day} عدد صحیح تقسیم شوند.
  • واحدها: پیش‌فرض روی METRIC است. اگر کاربر استانداردهای ایالات متحده را به‌طور ضمنی یا صریح درخواست کرد، units_system را روی IMPERIAL برای فارنهایت/مایل تنظیم کنید.

  • برونداد مستند باید بااستفاده از اطلاعات فیلد attribution (درصورت وجود) به منبع نسبت داده شود.
compute_routes

مسیرهای سفر بین مبدأ و مقصد را محاسبه می‌کند، به‌طور اختیاری ازطریق توقف‌های میانی. مسافت و مدت‌زمان هر مسیر را برمی‌گرداند.

الزامات ورودی (بسیار مهم):

  1. origin و destination (اشیاء - اجباری): هرکدام باید دقیقاً بااستفاده از یکی از موارد زیر ارائه شوند:

    • address (رشته، مثلاً 'Eiffel Tower, Paris'). مکان‌های نام‌گذاری‌شده، نشانگرهای مکانی، و کسب‌وکارها مستقیماً حل‌وفصل می‌شوند، بنابراین برای زمین‌کدیابی نقطه‌مسیر، ابتدا search_places را فراخوانی نکنید. هر شهر، منطقه، یا کشوری را که کاربر ذکر کرده است اضافه کنید.
    • lat_lng (شیء، {"latitude": number, "longitude": number}).
    • ‫place_id (رشته، مثلاً 'ChIJOwE_Id1w5EAR4Q27FkL6T_0')، برای مثال از search_places.

  2. intermediate_waypoints (آرایه اشیا - اختیاری): حداکثر ۱۰ ایستگاه برای عبور، به‌ترتیب، بین مبدأ و مقصد. قالب مشابه origin. با TRANSIT پشتیبانی نمی‌شود. فقط ایستگاه‌هایی را که کاربر درخواست کرده است اضافه کنید.

  3. travel_mode (enum - اختیاری): DRIVE (پیش‌فرض)، WALK، BICYCLE، یا TRANSIT.

  4. زمان‌بندی (اختیاری - حداکثر یک مورد تنظیم شود): مُهرهای زمان RFC 3339 با انحراف UTC، برای نمونه '2026-09-19T08:00:00-07:00'. به‌طور پیش‌فرض روی «درحال حرکت» تنظیم شده است. برای TRANSIT، زمان می‌تواند حداکثر ۷ روز در گذشته یا حداکثر ۱۰۰ روز در آینده باشد. برای حالت‌های دیگر، زمان می‌تواند تا ۳۶۵ روز در آینده باشد و نباید در گذشته باشد.

    • departure_time: زمانی استفاده می‌شود که کاربر می‌گوید چه زمانی می‌رود (مثلاً «فردا ساعت ۸ صبح»).
    • arrival_time: زمانی استفاده می‌شود که کاربر می‌گوید چه زمانی باید برسد (مثلاً «تا ساعت ۹ صبح آنجا باشم»).

  5. routing_preference (enum - اختیاری):

    • ROUTING_PREFERENCE_TRAFFIC_UNAWARE (پیش‌فرض): ترافیک زنده، حوادث، و راه‌بندان‌ها را نادیده می‌گیرد. کمترین تأخیر.
    • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL: از شرایط ترافیک زنده درصورت دردسترس بودن استفاده می‌کند. برای WALK یا BICYCLE پشتیبانی نمی‌شود. این را «فقط» زمانی تنظیم کنید که کاربر درباره ترافیک، ازدحام، یا زمان تخمینی ورود اصلاح‌شده براساس ترافیک سؤال می‌کند. این کار هزینه و تأخیر بیشتری دارد.

  6. location_bias (شیء - اختیاری): {"latitude": number, "longitude": number} برای ابهام‌زدایی از نام مکان‌ها در نشانی‌های نقطه‌مسیر استفاده می‌شود. اگر نامی مبهم است (مثلاً «Springfield») و کاربر منطقه‌ای را ارائه نکرده است، نام را همان‌طور که در address ارائه شده است نگه دارید و location_bias را به‌جای حدس زدن منطقه، به‌سمت منطقه موردنظر تنظیم کنید.

  7. compute_alternative_routes (بولی - اختیاری): فقط زمانی روی true تنظیم کنید که کاربر گزینه‌های مسیر یا جایگزین‌ها را درخواست کند. به‌طور پیش‌فرض روی false تنظیم شده است که فقط مسیر توصیه‌شده را برمی‌گرداند.

  8. include_polyline (بولی - اختیاری): فقط زمانی روی true تنظیم کنید که هندسه مسیر (encoded_polyline) موردنیاز باشد. پیش‌فرض‌ها به false.

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

  • اگر مبدأ یا مقصد وجود ندارد، باید قبل‌از فراخوانی ابزار از کاربر بخواهید شفاف‌سازی کند.
  • برای سؤالات «فاصله الف تا ب چقدر است؟»، از ب به‌عنوان origin و از الف به‌عنوان destination استفاده کنید.

نمونه فراخوانی ابزار: {"origin":{"address":"Eiffel Tower"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"intermediate_waypoints":[{"address":"Louvre Museum"}],"travel_mode":"DRIVE","departure_time":"2026-09-19T08:00:00+02:00"}

دستورالعمل‌های پاسخ:

  • وقتی مسیرهای جایگزین درخواست می‌شود، مسیرها از بیشترین به کمترین توصیه مرتب می‌شوند.
  • اگر routes خالی است، به کاربر بگو هیچ مسیری پیدا نشد. مسیر را حدس نزنید.
  • فقط حقایق برگردانده‌شده توسط ابزار را بیان کن. مسیرهای گام‌به‌گام، خطوط حمل‌ونقل عمومی، ایستگاه‌ها، سکوها، یا انتقالات را جعل نکنید.
  • برونداد مستندشده باید بااستفاده از فیلد attribution هر مسیر (درصورت دردسترس بودن) به منبع نسبت داده شود.
resolve_names

فهرست دسته‌ای از پُرسمان‌های مکان خاص (نام نشانگرهای مکانی یا نشانی‌های دقیق) را به «شناسه‌های جا» در Google Maps متعارف تبدیل می‌کند.

الزامات ورودی (بسیار مهم):

  1. queries (آرایه اشیاء - اجباری): فهرستی از پرسمان‌های مکان برای حل کردن. می‌توانید حداکثر ۲۰ پُرسمان مشخص کنید.

    • هر شیء پُرسمان باید دارای موارد زیر باشد:
      • text (رشته - اجباری): پُرسمان نوشتاری که نشان‌دهنده نام یا نشانی مکان خاصی برای حل‌وفصل است.
        • نمونه‌ها: 'Googleplex, Mountain View, CA'، '1600 Amphitheatre Pkwy, Mountain View, CA'، 'Eiffel Tower, Paris'.

  2. location_bias (شیء - اختیاری): از این مورد برای اولویت‌بندی نتایج نزدیک به یک منطقه جغرافیایی خاص استفاده کنید.

    • قالب: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

  3. ‫region_code (رشته - اختیاری): کد منطقه Unicode CLDR (کد کشور دوحرفی، مثلاً US، CA) کاربر برای سوگیری نتایج.

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

  • خاص بودن (بسیار مهم): پُرسمان‌ها باید نام یا نشانی مکان خاصی را نشان دهند. جستجوهای عمومی مانند 'restaurants' یا نام‌های زنجیره‌ای مانند 'Starbucks' پشتیبانی نمی‌شوند.
  • اگر ابزارهای پایین‌دستی که قصد دارید فراخوانی کنید ازقبل رشته‌های نشانی یا نام مکان خام را مستقیماً می‌پذیرند، این ابزار را فراخوانی نکنید.

ذخیره در Google Maps:

  • پاسخ شامل فیلد save_to_maps_url است: یک پیوند Google Maps که حاوی همه مکان‌های با موفقیت حل‌شده است.
  • وقتی کاربر می‌خواهد مکان‌های حل‌شده را به‌عنوان فهرست در Google Maps ذخیره، هم‌رسانی، یا باز کند، این پیوند را به کاربر ارائه دهید. این پیوند را خودتان نسازید.

مدیریت خطا (بسیار مهم):

  • این ابزار پردازش دسته‌ای است. ممکن است درخواستی «نتایج مختلط» برگرداند (مثلاً برخی‌از پُرسمان‌ها با موفقیت حل‌وفصل شوند درحالی‌که برخی دیگر ناموفق باشند).
  • تضمین می‌شود که فهرست خروجی results با نمایه‌های ورودی queries به‌صورت ۱:۱ نگاشت شود. پرسمان ناموفق منجر به پیام Result خالی (هیچ entity تنظیم نشده است) در نمایه مربوطه در فهرست results می‌شود.
  • باید فیلد نقشه failed_requests را در پاسخ بررسی کنید تا مشخص شود کدام نمایه پُرسمان خاص ناموفق بوده است. کلید failed_requests نشان‌دهنده نمایه مبتنی بر صفر پُرسمان ناموفق در درخواست است. فرض نکنید که کل تماس دسته‌ای به‌دلیل یک شکست جزئی ناموفق بوده است.
resolve_maps_urls

فهرستی از نشانی‌های وب Google Maps را به «شناسه‌های جا» در Google Maps متعارف تبدیل می‌کند.

چه زمانی این ابزار را فراخوانی کنید (بسیار مهم):

  • وقتی کاربر یک یا چند پیوند یا نشانی وب هم‌رسانی Google Maps (مثلاً «https://maps.app.goo.gl/...») ارائه می‌دهد، از این ابزار استفاده کنید. «https://www.google.com/maps/place/...‎» یا «https://maps.google.com/...‎») و باید «شناسه‌های مکان» متعارف زیربنایی را استخراج کنید.
  • می‌توانید حداکثر ۲۰ نشانی وب را برای حل‌وفصل در یک درخواست دسته‌ای مشخص کنید.

الزامات ورودی (بسیار مهم):

  • urls (آرایه رشته‌ها - اجباری): فهرست نشانی‌های وب Google Maps برای حل کردن. هر نشانی وب باید نشانی وب معتبر و تک‌مکانی Google Maps باشد.

ذخیره در Google Maps:

  • پاسخ شامل فیلد save_to_maps_url است: یک پیوند Google Maps که حاوی همه مکان‌های با موفقیت حل‌شده است.
  • وقتی کاربر می‌خواهد مکان‌های حل‌شده را به‌عنوان فهرستی در Google Maps ذخیره، هم‌رسانی، یا باز کند (مثلاً جمع‌آوری مکان‌های هم‌رسانی‌شده در مکالمه)، این پیوند را به کاربر ارائه دهید. این پیوند را خودتان نسازید.

مدیریت خطا (بسیار مهم):

  • این ابزار پردازش دسته‌ای است. ممکن است درخواست «نتایج مختلط» برگرداند (مثلاً برخی‌از نشانی‌های وب با موفقیت حل‌وفصل شوند درحالی‌که برخی دیگر ناموفق باشند).
  • تضمین می‌شود که فهرست خروجی entities با نمایه‌های ورودی urls به‌صورت ۱:۱ نگاشت شود. وضوح نشانی وب ناموفق منجر به پیام Entity خالی (هیچ فیلدی تنظیم نشده است) در نمایه مربوطه در فهرست entities می‌شود.
  • باید فیلد نقشه failed_requests را در پاسخ بررسی کنید تا مشخص شود کدام نمایه نشانی وب خاص ناموفق بوده است. کلید failed_requests نشان‌دهنده نمایه مبتنی بر صفر نشانی وب ناموفق در درخواست است. فرض نکنید که کل تماس دسته‌ای به‌دلیل یک شکست جزئی ناموفق بوده است.

دریافت مشخصات ابزار MCP

برای دریافت مشخصات ابزار MCP برای همه ابزارهای موجود در سرور MCP، از روش tools/list استفاده کنید. مثال زیر نشان می‌دهد که چگونه می‌توان از curl برای فهرست کردن همه ابزارها و مشخصات آن‌ها که درحال‌حاضر در سرور MCP دردسترس هستند استفاده کرد.

درخواست Curl 
curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
    "method": "tools/list",
    "jsonrpc": "2.0",
    "id": 1
}'