MCP Reference: mapstools.googleapis.com

지도 환경 에이전트 도구에서 제공하는 MCP 서버입니다. 이 서버는 개발자가 Google Maps Platform을 기반으로 LLM 애플리케이션을 빌드할 수 있는 도구를 제공합니다.

모델 컨텍스트 프로토콜 (MCP) 서버는 대규모 언어 모델 (LLM) 또는 AI 애플리케이션에 컨텍스트, 데이터 또는 기능을 제공하는 외부 서비스 간의 프록시 역할을 합니다. MCP 서버는 AI 애플리케이션을 데이터베이스 및 웹 서비스와 같은 외부 시스템에 연결하여 응답을 AI 애플리케이션이 이해할 수 있는 형식으로 변환합니다.

서버 설정

사용하기 전에 MCP 서버를 사용 설정하고 인증을 설정해야 합니다. Google 및 Google Cloud 원격 MCP 서버 사용에 대한 자세한 내용은 Google Cloud MCP 서버 개요를 참조하세요.

서버 엔드포인트

MCP 서비스 엔드포인트는 AI 애플리케이션 (MCP 클라이언트의 호스트)이 안전하고 표준화된 연결을 설정하는 데 사용하는 MCP 서버의 네트워크 주소 및 통신 인터페이스 (일반적으로 URL)입니다. LLM이 컨텍스트를 요청하거나, 도구를 호출하거나, 리소스에 액세스하는 연락 지점입니다. Google MCP 엔드포인트는 전역 또는 리전일 수 있습니다.

지도 환경 에이전트 도구 MCP 서버에는 다음과 같은 전역 MCP 엔드포인트가 있습니다.

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

MCP 도구

MCP 도구는 MCP 서버가 LLM 또는 AI 애플리케이션에 노출하여 실제 세계에서 작업을 수행하는 함수 또는 실행 가능한 기능입니다.

도구

mapstools.googleapis.com MCP 서버에는 다음 도구가 있습니다.

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)]}}}
    • 사용량:
      • 반경 5km로 편향: {"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}}} // 로스앤젤레스

  2. 장소 ID (place_id)

    • 명확한 문자열 식별자 (Google 지도 장소 ID)입니다.
    • place_id는 search_places 도구에서 가져올 수 있습니다.
    • 예: {"location": {"place_id": "ChIJLU7jZClu5kcR4PcOOO6p3I0"}} // 에펠탑

  3. 주소 문자열 (address)

    • 지오코딩에 대한 구체성이 필요한 자유 형식 문자열입니다.
    • 도시 및 지역: 항상 지역/국가를 포함합니다 (예: '런던'이 아닌 '영국 런던').
    • 상세 주소: 전체 주소를 입력합니다 (예: '1600 Pennsylvania Ave NW, Washington, DC').
    • 우편번호: 국가 이름이 함께 표시되어야 합니다 (예: '90210'이 아닌 '90210, USA').
    • 예: {"location": {"address": "1600 Pennsylvania Ave NW, Washington, DC"}}

사용 모드:

  • 현재 날씨: location만 제공합니다. date 및 hour를 지정하지 마세요.

  • 시간별 예측: location, date, hour (0~23)을 제공합니다. 특정 시간 (예: '오후 5시') 또는 '다음 몇 시간' 또는 '오늘 중'과 같은 용어에 사용합니다. 사용자가 분을 지정하면 가장 가까운 시간으로 반내림합니다. 지금부터 120시간 이후의 시간별 예보는 지원되지 않습니다. 과거 시간별 날씨는 최대 24시간 전까지 지원됩니다.

  • 일일 예측: location 및 date를 제공합니다. hour를 지정하지 마세요. 일반적인 날짜 요청에 사용합니다 (예: '내일 날씨', '금요일 날씨', '12월 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. Timing(선택사항 - 최대 1개 설정): UTC 오프셋이 있는 RFC 3339 타임스탬프(예: '2026-09-19T08:00:00-07:00') 기본값은 지금 출발입니다. TRANSIT의 경우 시간은 과거 최대 7일 또는 미래 최대 100일일 수 있습니다. 다른 모드의 경우 시간은 미래의 최대 365일일 수 있으며 과거가 아니어야 합니다.

    • departure_time: 사용자가 출발 시간을 말할 때 사용합니다 (예: '내일 오전 8시').
    • arrival_time: 사용자가 도착해야 하는 시간을 말할 때 사용합니다 (예: '오전 9시까지 도착').

  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 (불리언 - 선택사항): 경로 도형 (encoded_polyline)이 필요한 경우에만 true로 설정합니다. 기본값은 false입니다.

도구 호출 안내:

  • 출발지 또는 목적지가 누락된 경우 도구를 호출하기 전에 사용자에게 명확한 설명을 요청해야 합니다.
  • 'A는 B에서 얼마나 멀리 떨어져 있나요?'라는 질문의 경우 B를 origin로, A를 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 지도 장소 ID로 변환합니다.

입력 요구사항 (중요):

  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 (문자열 - 선택사항): 결과에 편향을 적용할 사용자의 유니코드 CLDR 리전 코드 (두 글자 국가 코드, 예: US, CA)입니다.

도구 호출 안내:

  • 구체성 (중요): 검색어는 특정 장소 이름 또는 주소를 나타내야 합니다. 'restaurants'와 같은 일반 검색어나 'Starbucks'와 같은 체인 이름은 지원되지 않습니다.
  • 호출하려는 다운스트림 도구가 이미 원시 주소 또는 장소 이름 문자열을 직접 허용하는 경우 이 도구를 호출하지 마세요.

Google 지도에 저장:

  • 응답에는 성공적으로 확인된 모든 장소가 포함된 단일 Google 지도 링크인 save_to_maps_url 필드가 포함됩니다.
  • 사용자가 확인된 장소를 Google 지도에서 목록으로 저장, 공유 또는 열려고 할 때 이 링크를 사용자에게 표시합니다. 이 링크를 직접 구성하지 마세요.

오류 처리 (중요):

  • 이 도구는 일괄 처리 도구입니다. 요청에서 '혼합된 결과'가 반환될 수 있습니다(예: 일부 쿼리는 성공적으로 해결되지만 다른 쿼리는 실패함).
  • results의 출력 목록은 입력 queries 색인과 1:1로 매핑됩니다. 쿼리가 실패하면 results 목록의 해당 색인에 빈 Result 메시지(entity가 설정되지 않음)가 표시됩니다.
  • 응답에서 failed_requests 맵 필드를 확인하여 실패한 특정 쿼리 색인을 식별해야 합니다. failed_requests의 키는 요청에서 실패한 쿼리의 0 기반 색인을 나타냅니다. 부분 실패로 인해 전체 일괄 호출이 실패했다고 가정하지 마세요.
resolve_maps_urls

Google 지도 URL 목록을 표준 Google 지도 장소 ID로 변환합니다.

이 도구를 호출해야 하는 경우 (중요):

  • 사용자가 하나 이상의 Google 지도 공유 링크 또는 URL (예: 'https://maps.app.goo.gl/…', 'https://www.google.com/maps/place/…' 또는 'https://maps.google.com/…')이 있고 기본 표준 장소 ID를 추출해야 하는 경우
  • 단일 일괄 요청에서 최대 20개의 URL을 지정하여 확인할 수 있습니다.

입력 요구사항 (중요):

  • urls (문자열 배열 - 필수): 확인할 Google 지도 URL 목록입니다. 각 URL은 유효한 단일 장소 Google 지도 URL이어야 합니다.

Google 지도에 저장:

  • 응답에는 성공적으로 확인된 모든 장소가 포함된 단일 Google 지도 링크인 save_to_maps_url 필드가 포함됩니다.
  • 사용자가 확인된 장소를 Google 지도에서 목록으로 저장, 공유 또는 열고 싶어 하는 경우 (예: 대화에서 공유된 장소 수집) 이 링크를 사용자에게 표시합니다. 이 링크를 직접 구성하지 마세요.

오류 처리 (중요):

  • 이 도구는 일괄 처리 도구입니다. 요청에서 '혼합된 결과'가 반환될 수 있습니다(예: 일부 URL은 성공적으로 확인되지만 다른 URL은 실패함).
  • entities의 출력 목록은 입력 urls 색인과 1:1로 매핑됩니다. URL 확인에 실패하면 entities 목록의 해당 색인에 빈 Entity 메시지 (필드가 설정되지 않음)가 표시됩니다.
  • 응답에서 failed_requests 맵 필드를 확인하여 실패한 특정 URL 색인을 식별해야 합니다. failed_requests 키는 요청에서 실패한 URL의 0 기반 색인을 나타냅니다. 부분 실패로 인해 전체 일괄 호출이 실패했다고 가정하지 마세요.

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
}'