MCP Reference: mapstools.googleapis.com

זהו שרת MCP שסופק על ידי Maps Experience Agent Tools. השרת מספק למפתחים כלים ליצירת אפליקציות LLM על גבי Google Maps Platform.

שרת Model Context Protocol‏ (MCP) פועל כשרת proxy בין שירות חיצוני שמספק הקשר, נתונים או יכולות לבין מודל שפה גדול (LLM) או אפליקציית AI. שרתי MCP מחברים בין אפליקציות AI למערכות חיצוניות כמו מסדי נתונים ושירותי אינטרנט, ומתרגמים את התשובות שלהם לפורמט שאפליקציית ה-AI יכולה להבין.

הגדרת השרת

כדי להשתמש בשרתי MCP, צריך להפעיל אותם ולהגדיר אימות. מידע נוסף על השימוש בשרתי MCP מרוחקים של Google ו-Google Cloud זמין במאמר סקירה כללית על שרתי MCP של Google Cloud.

נקודות קצה של שרתים

נקודת קצה של שירות MCP היא כתובת הרשת וממשק התקשורת (בדרך כלל כתובת URL) של שרת ה-MCP, שאפליקציית AI (המארח של לקוח ה-MCP) משתמשת בהם כדי ליצור חיבור מאובטח וסטנדרטי. הוא משמש כנקודת הקשר של ה-LLM לבקשת הקשר, להפעלת כלי או לגישה למשאב. נקודות הקצה של Google MCP יכולות להיות גלובליות או אזוריות.

לשרת ה-MCP של Maps Experience Agent Tools יש את נקודת הקצה הגלובלית הבאה של MCP:

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

כלי MCP

כלי MCP הוא פונקציה או יכולת הפעלה ששרת MCP חושף למודל שפה גדול (LLM) או לאפליקציית AI כדי לבצע פעולה בעולם האמיתי.

כלים

בשרת ה-MCP של mapstools.googleapis.com יש את הכלים הבאים:

כלי MCP
search_places

צריך להפעיל את הכלי הזה כשהמשתמש מבקש למצוא מקומות, עסקים, כתובות, מיקומים, נקודות עניין או כל חיפוש אחר שקשור למפות Google.

דרישות קלט (קריטי):

  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)]}}}
    • שימוש:
      • כדי להטות לרדיוס של 5 ק"מ: {"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 של Unicode. הפרמטר הזה משמש להצגת פרטי המקום, כמו שם המקום הספציפי לאזור, אם הוא זמין. הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.

    • פורמט: קוד מדינה בן שתי אותיות (ISO 3166-1 alpha-2), לדוגמה, US, CA.

הוראות לקריאה לפונקציה:

  • נתוני מיקום (קריטי): החיפוש חייב להכיל מספיק נתוני מיקום. אם המיקום לא ברור (למשל, רק "פיצריות"), חובה לציין אותו בפרמטר text_query (למשל, "פיצריות בניו יורק") או להשתמש בפרמטר location_bias. אם צריך, כדי למנוע בלבול, אפשר לכלול את שם העיר, המדינה/המחוז והאזור/המדינה.

  • תמיד צריך לספק את ה-text_query הכי ספציפי ועשיר בהקשר שאפשר.

  • צריך להשתמש ב-location_bias רק אם הקואורדינטות צוינו במפורש או אם מתאים להסיק את המיקום מההקשר הידוע של המשתמש וגם אם זה נחוץ כדי לקבל תוצאות טובות יותר.

  • הפלט המבוסס חייב להיות משויך למקור באמצעות המידע מהשדה attribution, אם הוא זמין.
lookup_weather

אחזור נתוני מזג אוויר מקיפים, כולל התנאים הנוכחיים, תחזיות לפי שעה ותחזיות יומיות.

נתונים ספציפיים שזמינים: טמפרטורה (נוכחית, טמפרטורה מורגשת, מקסימום/מינימום, אינדקס חום), רוח (מהירות, משבים, כיוון), אירועים שמימיים (זריחה/שקיעה, מופע הירח), משקעים (סוג, סבירות, כמות/QPF), תנאים אטמוספריים (מדד קרינת UV, לחות, כיסוי עננים, סבירות לסופת רעמים) וכתובת מיקום שהומרה לקואורדינטות.

מיקום וכללים שמתייחסים למיקום (קריטי):

המיקום שלגביו מתבקשים נתוני מזג האוויר מצוין בשדה location. השדה הזה הוא מבנה מסוג "oneof", כלומר חובה לספק ערך רק לאחד משלושת שדות המשנה של המיקום שבהמשך כדי להבטיח חיפוש מדויק של נתוני מזג האוויר.

  1. קואורדינטות גיאוגרפיות (lat_lng)

    • כדאי להשתמש בו כשמקבלים קואורדינטות מדויקות של קו רוחב/אורך.
    • לדוגמה: ‎{"location": {"lat_lng": {"latitude": 34.0522, "longitude": -118.2437}}}‎ // לוס אנג'לס

  2. מזהה מקום (place_id)

    • מזהה מחרוזת חד-משמעי (מזהה מקום במפות Google).
    • אפשר לאחזר את ה-place_id מהכלי search_places.
    • דוגמה: ‎{"location": {"place_id": "ChIJLU7jZClu5kcR4PcOOO6p3I0"}}‎ // מגדל אייפל

  3. מחרוזת כתובת (address)

    • מחרוזת בפורמט חופשי שצריכה להיות ספציפית כדי שאפשר יהיה להמיר אותה לקואורדינטות.
    • עיר ואזור: תמיד צריך לכלול את האזור או המדינה (למשל, "לונדון, בריטניה" ולא "לונדון").
    • כתובת: הכתובת המלאה (לדוגמה, "רחוב בן יהודה 1, תל אביב").
    • מיקוד: חובה לצרף שם מדינה (למשל, "90210, ארה"ב", ולא "90210").
    • דוגמה: {"location": {"address": "1600 Pennsylvania Ave NW, Washington, DC"}}

מצבי שימוש:

  • מזג האוויר הנוכחי: צריך לספק רק את location. אל תציינו את date ו-hour.

  • תחזית שעתית: צריך לציין את location, date ו-hour (0-23). אפשר להשתמש בשעות ספציפיות (למשל, "ב-17:00") או במונחים כמו "בשעות הקרובות" או "מאוחר יותר היום". אם המשתמש מציין דקה, מעגלים כלפי מטה לשעה הקרובה. אין תמיכה בתחזית לפי שעה מעבר ל-120 שעות מעכשיו. אפשר לקבל נתונים היסטוריים של מזג אוויר שעתי עד 24 שעות אחורה.

  • תחזית יומית: צריך לספק את location ו-date. אל תציינו את hour. משתמשים בפורמט הזה לבקשות כלליות לגבי ימים (למשל, "מזג האוויר מחר", "מזג האוויר ביום שישי", "מזג האוויר ב-25 בדצמבר"). אם התאריך של היום לא מופיע בהקשר, צריך לבקש מהמשתמש להבהיר אותו. אין תמיכה בתחזית יומית של יותר מ-10 ימים, כולל היום. אין תמיכה בנתוני מזג אוויר היסטוריים.

אילוצי פרמטרים:

  • אזורי זמן: כל הערכים של 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 (מערך של אובייקטים – אופציונלי): עד 10 עצירות שצריך לעבור בהן, לפי הסדר, בין נקודת המוצא ליעד. אותו פורמט כמו origin. אין תמיכה ב-TRANSIT. לכלול רק עצירות שהמשתמש ביקש.

  3. ‫travel_mode (enum – אופציונלי): DRIVE (ברירת מחדל), WALK,‏ BICYCLE או TRANSIT.

  4. תזמון (אופציונלי – אפשר להגדיר לכל היותר אחד): חותמות זמן בפורמט RFC 3339 עם הפרש משעון UTC, למשל '2026-09-19T08:00:00-07:00'. ברירת המחדל היא יציאה עכשיו. בשדה TRANSIT, אפשר להזין תאריך עד 7 ימים בעבר או עד 100 ימים בעתיד. במצבים אחרים, אפשר להגדיר את השעה עד 365 ימים בעתיד, והיא לא יכולה להיות בעבר.

    • ‫departure_time: משתמשים בפרמטר הזה כשהמשתמש מציין מתי הוא ייצא (למשל, "מחר ב-8:00").
    • ‫arrival_time: משתמשים בפרמטר הזה כשהמשתמש מציין מתי הוא צריך להגיע (למשל, "להגיע עד 9:00").

  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.

דרישות קלט (קריטי):

  1. queries (מערך של אובייקטים – חובה): רשימה של שאילתות מיקום שצריך לפתור. אפשר לציין עד 20 שאילתות.

    • כל אובייקט שאילתה חייב לכלול:
      • 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:

  • התשובה כוללת את השדה save_to_maps_url: קישור אחד למפות Google שמכיל את כל המקומות שנמצאו.
  • כשהמשתמש רוצה לשמור, לשתף או לפתוח את המקומות שנמצאו כרשימה במפות Google, צריך להציג לו את הקישור הזה. אל תיצרו את הקישור הזה בעצמכם.

טיפול בשגיאות (קריטי):

  • זהו כלי לעיבוד ברצף (batch processing). יכול להיות שבקשה תחזיר "תוצאות מעורבות" (למשל, חלק מהשאילתות יטופלו בהצלחה ואחרות ייכשלו).
  • רשימת הפלט של results ממופה בהכרח ביחס של 1:1 עם האינדקסים של הקלט queries. שאילתה שנכשלה תגרום להודעת Result ריקה (לא מוגדר entity) באינדקס התואם שלה ברשימה results.
  • חובה לבדוק את השדה failed_requests בתגובה כדי לזהות את אינדקס השאילתה הספציפי שנכשל. המפתח של failed_requests מייצג את האינדקס מבוסס-האפס של השאילתה שנכשלה בבקשה. אל תניחו שכל הקריאה באצווה נכשלה בגלל כישלון חלקי.
resolve_maps_urls

הפונקציה מקבלת רשימה של כתובות URL של מפות Google ומחזירה את מזהי המקומות הקנוניים שלהן במפות Google.

מתי להפעיל את הכלי הזה (חשוב מאוד):

  • צריך להשתמש בכלי הזה כשהמשתמש מספק כתובת URL אחת או יותר או קישור אחד או יותר לשיתוף במפות Google (למשל, "https://maps.app.goo.gl/...‎", ‫'https://www.google.com/maps/place/...‎' או 'https://maps.google.com/...‎') ואתם צריכים לחלץ את מזהי המקומות הקנוניים שבבסיס.
  • אפשר לציין עד 20 כתובות URL לפתרון בבקשת Batch אחת.

דרישות קלט (קריטי):

  • urls (מערך של מחרוזות – חובה): רשימת כתובות ה-URL של מפות Google שצריך לפתור. כל כתובת URL צריכה להיות כתובת URL תקינה של מקום אחד במפות Google.

שמירה במפות Google:

  • התשובה כוללת את השדה save_to_maps_url: קישור אחד למפות Google שמכיל את כל המקומות שנמצאו.
  • כשהמשתמש רוצה לשמור, לשתף או לפתוח את המקומות שנמצאו כרשימה במפות Google (למשל, לאסוף מקומות ששותפו בשיחה), צריך להציג למשתמש את הקישור הזה. אל תיצרו את הקישור הזה בעצמכם.

טיפול בשגיאות (קריטי):

  • זהו כלי לעיבוד ברצף (batch processing). יכול להיות שבקשה תחזיר "תוצאות מעורבות" (למשל, חלק מכתובות ה-URL נפתרות בהצלחה ואחרות נכשלות).
  • רשימת הפלט של entities ממופה בהכרח ביחס של 1:1 עם האינדקסים של הקלט urls. אם פתרון כתובת ה-URL נכשל, תתקבל הודעת Entity ריקה (לא הוגדרו שדות) באינדקס התואם ברשימה entities.
  • חובה לבדוק את שדה המפה failed_requests בתגובה כדי לזהות את האינדקס של כתובת ה-URL הספציפית שנכשלה. המפתח של failed_requests מייצג את האינדקס מבוסס-האפס של כתובת ה-URL שנכשלה בבקשה. אל תניחו שכל הקריאה באצווה נכשלה בגלל כישלון חלקי.

קבלת מפרטים של כלי MCP

כדי לקבל את המפרטים של כל הכלים בשרת MCP, משתמשים ב-method‏ 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
}'