Google Maps MCP Server

Claude, Cursor, Windsurf 및 기타 모든 MCP 클라이언트에 6가지 읽기 전용 Google Maps 도구를 제공하는 호스팅형 Model Context Protocol (MCP) 서버입니다. 장소를 검색하고, 장소 전체를 읽고, 리뷰·사진·게시물을 가져오고, 개별 리뷰어의 작성 이력을 살펴볼 수 있으며, 모두 구조화된 JSON으로 제공됩니다. Google Cloud 프로젝트나 청구 설정 없이 사용할 수 있습니다.

https://mcp.hasdata.com/api/mcp?apis=google_maps

목차

• 준비 사항

• 빠른 시작

• 예시 프롬프트

• 도구

• 오류 및 실패 경로

• 가격, 무료 티어 및 한도

• 도구 선택

• 비교

• FAQ

• HasData 링크

• 개발

• 기여

• 라이선스

Related MCP server: MCP Google Maps

필요한 것

사용자 지정 헤더로 streamable HTTP를 지원하는 MCP 클라이언트. 대시보드에서 HasData API 키를 만들면 됩니다. 카드 없이 무료로 생성할 수 있고, 체험판은 5크레딧 요율로 약 200회 호출을 포함합니다. 그 외에는 아무것도 필요 없습니다. 이 서버는 원격 서버이므로 가장 간단한 방법은 URL과 헤더 하나로 끝나는 것이며, 실행할 컨테이너도, Google Cloud 프로젝트나 API 키도 전혀 필요 없습니다. stdio 전용 클라이언트는 대신 @hasdata/google-maps-mcp (npm) 또는 hasdata-google-maps-mcp (PyPI) 런처를 사용할 수 있습니다.

빠른 시작

서버 URL은 모든 클라이언트에서 동일합니다. 직접 Claude Code 및 Claude Desktop에서 실행합니다. 다른 블록은 각 클라이언트 자체 문서에 명시된 원격 서버 형식을 따릅니다.

OAuth를 지원하는 클라이언트는 동일한 URL을 커넥터로 추가하고 설정 파일에 키를 넣지 않고 로그인할 수 있습니다.

claude mcp add --transport http google-maps "https://mcp.hasdata.com/api/mcp?apis=google_maps" \
  --header "x-api-key: HASDATA_API_KEY"

Claude Desktop은 설정 파일에서 로컬(stdio) 서버만 불러오므로 원격 서버에는 stdio 런처를 통해 접근합니다. @hasdata/google-maps-mcp 패키지가 바로 그 런처이며, 환경 변수에서 키를 읽습니다.

claude_desktop_config.json:

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": ["-y", "@hasdata/google-maps-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

Python의 경우? 런처를 PyPI 패키지로 바꾸면 되며, uvx가 수동 설치 없이 실행해 줍니다:

{
  "mcpServers": {
    "google-maps": {
      "command": "uvx",
      "args": ["hasdata-google-maps-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

OAuth를 지원하는 클라이언트는 대신 URL을 사용자 지정 커넥터로 추가하고 런처를 건너뛸 수 있습니다.

.cursor/mcp.json:

{
  "mcpServers": {
    "google-maps": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=google_maps",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "google-maps": {
      "serverUrl": "https://mcp.hasdata.com/api/mcp?apis=google_maps",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

{
  "mcpServers": {
    "google-maps": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=google_maps",
      "type": "streamableHttp",
      "headers": { "x-api-key": "HASDATA_API_KEY" },
      "disabled": false
    }
  }
}

.vscode/mcp.json:

{
  "servers": {
    "google-maps": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=google_maps",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

~/.gemini/settings.json:

{
  "mcpServers": {
    "google-maps": {
      "httpUrl": "https://mcp.hasdata.com/api/mcp?apis=google_maps",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

예시 프롬프트

다음 각 항목은 횟수에 달리 나와 있지 않는 한 한 번의 도구 호출입니다.

Google Maps에서 시애틀 다운타운 근처 커피를 검색하고, 평점·리뷰 수·웹사이트를 포함해 상위 10곳을 알려줘.

한 번 호출, 5크레딧. 검색 결과에는 placeId와 dataId가 이미 포함되어 있어, 아래 후속 호출에 별도의 조회 단계가 필요 없습니다.

ChIJAb0KE0RrkFQRuI4X0By5Mcw에 대한 전체 상세 정보를 불러와: 영업 시간, 서비스 옵션, 가성비 수준, 메뉴 링크.

한 번 호출, 5크레딧.

그 장소에 대한 최신 리뷰를 최신순으로 읽고, 가장 자주 언급되는 주제가 무엇인지 알려줘.

한 번 호출, 5크레딧. 응답에는 Google이 자체적으로 분류한 주제 묶음과 각각의 언급 수가 포함되며, 순위는 데이터 안에 들어 있습니다.

상단 리뷰의 작성자를 기준으로 그 사람이 리뷰한 다른 모든 장소를 각각 남긴 평점과 함께 나열해.

한 번 호출, 5크레딧. 리뷰에는 작성자의 contributorId가 포함되어 있으며, 이것이 바로 contributor 도구가 입력으로 받는 값입니다.

해당 장소의 사진 피드와 업체의 최근 게시물을 가져와.

두 번의 호출. 사진은 5크레딧, 게시물은 10크레딧.

이러한 체인이 저렴한 이유는 두 가지입니다. 검색은 모든 결과에 placeId와 dataId를 반환하며, 상세·리뷰·사진·게시물 호출에는 별도의 해석 단계가 필요 없습니다. 또한 리뷰에는 작성자의 contributorId가 포함되어 있어 "이 리뷰를 남긴 사람은 누구인가"를 그 사람의 전체 이력으로 한 번의 호출로 넘어갈 수 있습니다.

도구

여섯 가지 도구, 모두 읽기 전용입니다. 아래 예시는 실제 호출에서 짧게 다듬은 것이며, 안의 숫자는 장소가 리뷰를 받을수록 변합니다. 형태를 참고하세요. 각 도구 이름은 해당 엔드포인트 문서로 연결됩니다.

샘플은 페이로드만 보여주지 전체 응답을 보여주는 것은 아닙니다. tools/call 결과에는 텍스트 블록이 하나 있으며, 그 텍스트 자체가 url, status, text, json을 담은 JSON이고 스크랩된 데이터는 json 아래에 있습니다. 원시 JSON-RPC 응답에서 경로는 result.content[0].text를 파싱한 뒤 .json입니다. 채팅 클라이언트는 이를 알아서 풀어주고, 엔드포인트에 직접 연결하는 코드는 직접 풀어야 합니다.

네 가지 도구는 placeId 또는 dataId 중 하나로 장소를 받습니다. 검색은 모든 결과에 둘 다 반환합니다. 일반적인 흐름은 검색 한 번 후, 유지한 id를 재사용하여 세부·리뷰·사진·게시물 호출을 하는 것입니다.

Google 지도 검색

hasdata_google_maps_search_performMapSearch

쿼리에 대한 장소를 Google 지도가 정렬하는 순위 그대로 반환합니다.

각 결과에는 position, title, placeId, dataId, address, gpsCoordinates, rating, reviews, type, types, price, website, thumbnail, openState, workingHours, serviceOptions 그리고 Google이 표시하는 경우 menu 링크가 포함됩니다.

위치는 쿼리가 아니라 ll에 들어갑니다. 맵 중심과 줌을 여기에 넣으세요. "coffee"만으로는 Google이 사용자가 있는 곳으로 결정한 위치가 반환됩니다. 줌 숫자는 결과를 뽑아낼 영역을 넓히거나 좁힙니다.

{
  "localResults": [
    {
      "position": 1,
      "title": "Howdy Y'all Coffee (Central Library)",
      "placeId": "ChIJAb0KE0RrkFQRuI4X0By5Mcw",
      "dataId": "0x54906b44130abd01:0xcc31b91cd0178eb8",
      "address": "1000 4th Ave Fl 3, Seattle, WA 98104",
      "rating": 4.9,
      "reviews": 117,
      "type": "Coffee shop",
      "website": "https://howdyyallcoffee.com/",
      "workingHours": {
        "timezone": "America/Los_Angeles",
        "days": [ { "day": "Friday", "time": "10 AM–4 PM" } ]
      }
    }
  ]
}

장소 상세 정보 가져오기

hasdata_google_maps_place_getPlaceDetails

placeId로 한 장소의 전체 정보를 가져옵니다.

검색 결과가 가진 동일한 필드에 images 배열을 추가한 하나의 placeResults 객관를 반환합니다. 필요 없는 검색을 실행하지 않고 한 장소의 전체 정보를 얻는 방법입니다.

장소 리뷰 가져오기

hasdata_google_maps_reviews_getMapReviews

한 장소의 리뷰 피드를 페이지별로 가져옵니다.

placeInfo, topics 배열, reviews 배열, pagination을 반환합니다. 각 리뷰에는 reviewId, rating, snippet, date, isoDate, link, images, user 객체, 그리고 업체 소유자가 답글을 단 경우에는 response가 포함됩니다.

topics는 Google이 리뷰에서 언급된 내용을 자체적으로 분류한 것으로, 각각 keyword와 mentions 수를 가지며, 모든 리뷰를 읽지 않아도 주제별 언급 수가 미리 계산되어 있습니다. 토우픽의 id를 topicId로 전달하면 해당 주제를 언급한 리뷰만 읽을 수 있습니다.

각 리뷰의 user에는 contributorId가 있습니다. 이것이 기여자 도구의 입력값이므로, "누가 리뷰를 썼는가"는 "그 사람이 쓴 모든 것"으로 한 번의 호출로 이어집니다.

{
  "placeInfo": { "title": "Howdy Y'all Coffee (Central Library)", "rating": 4.9, "reviews": 117 },
  "topics": [
    { "keyword": "earl grey matcha", "mentions": 26, "id": "bew1w_KAk5U" },
    { "keyword": "friendly baristas", "mentions": 17, "id": "FOw-91tYieQ" }
  ],
  "reviews": [
    {
      "reviewId": "…",
      "rating": 5,
      "snippet": "…",
      "isoDate": "2026-07-06T19:49:00.657Z",
      "user": { "name": "Angela Li", "contributorId": "106033685843245983748" },
      "response": { "isoDate": "2026-07-07T04:44:34.000Z", "snippet": "Thank you!! 🥺☺️" }
    }
  ],
  "pagination": { "nextPageToken": "…" }
}

기여자가 쓴 리뷰 가져오기

hasdata_google_maps_contributor_reviews_getMapReviews

한 사람이 평점을 남긴 모든 장소에서, 그 사람이 작성한 모든 리뷰를 가져옵니다.

name, level, points 및 contributions 상세 내역이 있는 contributor 객체와, 각 항목에 자체 placeInfo가 포함된 reviews 배열을 반환합니다. 각 리뷰가 어떤 장소에 관한 것인지 추가 조회 없이 알 수 있습니다. 이 도구는 리뷰 피드만으로는 불가능한 리뷰어 신뢰도 및 리뷰 네트워크 분석 작업을 지원합니다. 한 개인의 공개 리뷰 기록을 읽는 것이므로, 결과는 Google의 약관과 적용되는 법률에 따라 사용해야 합니다.

장소 사진 가져오기

hasdata_google_maps_photos_getMapPhotos

장소에 대한 사진 피드입니다.

응답에는 categories 배열(All, Latest, Videos, Menu 및 장소별 카테고리), 각 항목에 image 및 thumbnail URL이 있는 photos 배열, 그리고 pagination이 포함됩니다.

장소 게시물 가져오기

hasdata_google_maps_posts_getMapPosts

비즈니스가 자체 Google 등록 정보에 게시한 게시물과 업데이트입니다.

posts 배열을 반환합니다.

대부분의 장소는 아무것도 게시하지 않으므로 빈 posts 배열이 일반적인 경우입니다. 게시물이 있다고 가정하기 전에 배열 길이를 확인하세요.

오류 및 실패 경로

클라이언트는 도구 호출에서 HTTP 오류 코드를 거의 보지 못합니다. MCP 계층은 200으로 응답하고 실패를 결과에 담아 isError를 true로 설정하고 이유를 텍스트로 넣습니다. 에이전트는 상태 줄을 기대하게 되는 지점에서 메시지를 읽게 됩니다.

잘못된 키는 연결 실패가 아니라 도구 출력으로 드러납니다. 도구 목록 조회는 비어 있지 않은 키를 모두 허용하며, 클라이언트는 핸드셰이크를 완료하고 정상 표시를 냅니다. 그러다 첫 번째 도구 호출이 isError: true와 HasData API error: 401 Unauthorized 텍스트로 반환됩니다. 해당 문자열을 주의하세요. 흐름의 앞부분에서는 이 문제를 알려주는 것이 없기 때문입니다.

유일한 실제 HTTP 오류는 키 누락입니다. 인증은 모든 도구 실행보다 먼저 진행되며, 연결 자체가 401로 실패합니다.

스키마를 위반하는 인자는 요청이 되기 전에 거부됩니다. q가 없는 검색은 isError: true와 함께 필드 이름을 명시한 MCP error -32602: Input validation error 텍스트를 반환합니다. 어떤 데이터도 가져오지 않으며 요금도 부과되지 않습니다.

리뷰, 사진, 게시물 호출에는 장소가 필요합니다. 이 세 호출은 placeId 또는 dataId를 받으며, 둘 중 하나도 보내지 않으면 두 필드를 모두 지목하는 422가 반환됩니다. 이 요구사항은 조건부이므로 스키마가 단순 필수 목록으로 표현할 수 없기 때문입니다. 하나는 전달하세요.

존재하지 않는 장소 ID는 빈 데이터가 아니라 깔끔한 오류로 처리됩니다. isError: true와 HasData API error: 400 Bad Request를 반환하고 requestMetadata.status는 error로 설정됩니다. 배열 길이 대신 그 플래그를 확인하세요.

빈 posts 배열은 정상 데이터입니다. 대부분의 등록에는 게시물이 없으므로 호출은 status가 ok인 상태로 성공하고 빈 배열을 반환합니다. 장소에 게시된 것이 없을 뿐입니다.

데이터를 담은 결과는 지원 요청에 인용할 만한 requestMetadata.id와, 해당 호출의 저장된 산출물로 연결되는 html 및 json 링크도 함께 포함합니다.

요금, 무료 티어 및 제한

검색, 장소 상세, 리뷰, 작성자 리뷰, 사진은 성공적인 호출당 5크레딧입니다. 게시물은 10크레딧입니다. 응답 크기는 가격을 바꾸지 않습니다. 리뷰가 가득한 페이지도 한 건만 있는 페이지와 같은 비용입니다.

무료 체험은 카드 없이 30일 동안 1,000크레딧이며, 5크레딧 기준으로 200회 호출입니다. 이후 활성 계정은 잔액이 100 미만으로 떨어질 때마다 매일 100크레딧을 충전받으므로, 소량 트래픽의 에이전트는 무료 티어에서 무기한 실행될 수 있습니다.

유료 플랜은 200,000크레딧 기준 월 49달러부터 시작하며, 이는 40,000회의 5크레딧 호출에 해당합니다. 크레딧당 가격은 볼륨에 따라 낮아지며, 현재 수치는 요금 페이지에서 확인할 수 있습니다.

플랜은 동시성도 결정합니다. 무료 체험은 한 번에 1개의 요청을 허용하고, Startup은 15, Business는 30, Growth는 50, 그리고 대용량 플랜은 200에서 1,500 사이입니다. 동시성이 유일한 제한 장치입니다. 분당 요청 수 상한은 따로 없으며, 체험판이 느려지거나 다른 방식으로 제한되지 않습니다. 무인 환경에서는 오버플로 상황을 방어적으로 처리하세요. 여러 장소를 동시에 조회하는 에이전트는 예상보다 빨리 한도에 도달하니까요.

페이지네이션은 호출할 때마다 비용이 듭니다. 리뷰는 페이지당 약 10개이므로 리뷰 100개는 대략 10회 호출과 50크레딧이 되고, 사진은 페이지당 20개입니다. 체험 크레딧은 부담을 느끼기 전까지 꽤 오래 쓸 수 있습니다.

도구 선택

?apis=google_maps는 정확히 이 여섯 가지 도구만 노출합니다. 이 파라미터는 목록을 받으며, ?apis=google_maps,google_serp는 지도 도구와 함께 Google 검색을 추가합니다. 파라미터를 생략하면 HasData가 노출하는 전체 도구, 현재 57개를 모두 가져옵니다.

좁은 목록이 보통 더 나은 기본값입니다. 57개 중에서 고르는 모델보다 6개 중에서 고르는 모델이 올바른 선택을 할 확률이 더 높고, 도구 설명 자체가 매 턴마다 컨텍스트를 소모하기 때문입니다.

비교

다른 거의 모든 Google Maps MCP 서버는 공식 Google Maps Platform을 래핑하고 있으며, 이는 저울 위에 놓고 실질적으로 비교할 대상입니다.

그런 서버들은 사용자 고유의 Google Cloud 자격 증명으로 각각 Places, Routes, Geocoding API를 호출합니다. 실행하려면 Google Cloud 프로젝트를 만들고, 카드로 결제를 활성화하고, 각 API를 켜고, 키와 쿼터를 관리해야 합니다. 경로 탐색, 지오코딩, 주소 검증이 필요하다면 그쪽을 선택하는 것이 옳습니다. 이 서버는 그런 기능을 제공하지 않습니다.

이 서버는 Google Maps가 방문자에게 보여주는 내용을 읽어 파싱된 형태로 반환합니다. Google Cloud 프로젝트도, 활성화할 카드 결제도, 관리할 API별 쿼터도 없습니다. 또한 Places API가 제공하지 않는 데이터에도 닿습니다. 즉 소수의 고정 표본이 아닌 전체 리뷰 피드, 한 리뷰어의 전체 기록, 사진 피드, 비즈니스의 게시물입니다.

결정은 두 사망으로 귀결됩니다. 경로 탐색이 필요하거나 주소를 좌표로 변환해야 한다면, 이 서버는 도울 수 없고 Platform은 도울 수 있습니다. 처음 몇 개 이상의 리뷰가 필요하거나, 리뷰어가 평점을 남긴 모든 장소에 걸쳐 그 리뷰어가 누구인지 알 필요가 있다면, Platform은 도울 수 없고 이 서버가 도울 수 있습니다.

이 서버가 하지 않는 일. 경로 탐색, 지오코딩, 주소 검증, 거리 행렬, 그리고 쓰기 작업은 없습니다. 지도의 내용을 읽을 뿐입니다.

FAQ

Google Maps MCP 서버란 무엇인가요?

Google Maps 데이터를 AI 클라이언트가 호출할 수 있는 도구로 노출하는 서버입니다. 클라이언트는 Model Context Protocol을 통해 도구 호출을 보내고, 서버는 데이터를 가져와 구조화된 JSON으로 반환하며, 모델은 결과를 가지고 작업합니다. HTML 페이지를 볼 필요가 없습니다. 이 서버는 여섯 가지 읽기 전용 도구를 노출하며 멀리 떨어진 원격에서 실행됩니다. 클라이언트는 URL에 연결하고 로컬 프로세스를 시작하지 않습니다.

공식 Google Maps MCP 서버가 있나요?

Google은 범용 서버를 공개하지 않습니다. Google Maps Platform이라는 자체 Cloud 프로젝트에서 호출하는 유료 API 세트가 있으며, 여러 커뮤니티 MCP 서버가 그것을 래핑합니다. 이 서버는 Cloud 프로젝트가 필요 없는 호스팅형 대안입니다.

Google Cloud 프로젝트나 Maps API 키가 필요하나요?

아니요. 필요한 자격 증명은 HasData 키 하나뿐입니다. 생성할 Google Cloud 프로젝트, 활성화할 결제, 관리할 API별 쿼터가 없습니다.

placeId와 dataId의 차이는 무엇인가요?

같은 장소에 Google이 사용하는 두 가지 ID입니다. 검색 결과는 항상 둘 다 반환하고, 상세·리뷰·사진·게시물 도구는 어느 하나를 허용합니다. 검색 결과에서 마음에 드는 것을 골라서 그대로 재사용하세요.

첫 페이지뿐만 아니라 모든 리뷰를 얻으려면 어때야 하나요?

각 응답에서 pagination.nextPageToken을 읽어 그것이 더 이상 오지 않을 때까지 nextPageToken으로 다시 전달하면 됩니다. 페이지마다 한 번의 호출이 필요합니다.

호스팅하거나 실행해야 할 것이 있나요?

아니요. 이 서버는 스트리밍 가능한 HTTP 위에 있는 원격 MCP 서버입니다. 설치할 것이 없고, Python 환경도 없으며, 재시작할 프로세스도 없습니다.

데이터는 실시간인가요 캐시인가요?

실시간입니다. 각 호출은 요청 시점에 데이터를 가져오고 고유한 requestMetadata.id를 담습니다. 두 번 실행한 동일한 호출은 저장본을 재생하는 것이 아니라 각각 별도의 수집입니다.

하나의 서버를 여러 Google 표면에서 사용할 수 있나요?

네. apis 파라미터는 목록을 받습니다. ?apis=google_maps,google_serp는 지도 도구와 Google 검색을 동시에 동원합니다.

API 키는 만료되나요?

아니요. 키는 만료되지 않습니다. 필요할 때만 대시보드에서 교체하세요.

Google와 제휴되어 있나요?

아니요. HasData는 독립 서비스로, Google의 제휴사나 보증·후원을 받지 않습니다. Google 및 Google Maps는 각 소유권자의 상표입니다. 이 도구들은 공개적으로 제공되는 데이터만 다루며, 결과를 Google의 약관과 적용되는 법률에 따라 사용할 책임은 사용자에게 있습니다.

HasData 링크

개발

이 저장소는 원격 서버의 구성과 문서입니다. 빌드 단계도 컨테이너화할 항목도 없습니다.

계약 테스트는 포함되어 있습니다. README는 특정 파라미터를 가진 6개의 도구를 약속하며, 업스트림 도구 목록은 이 저장소에 커밋 없이 변경될 수 있습니다. 그러면 이 파일이 조용히 사실과 다른 내용을 알려주게 됩니다. 테스트는 이 약속을 검증하며, 모든 푸시 빈도뿐만 아니라 CI에서도 매주 실행됩니다.

HASDATA_API_KEY=your_key_here npm test

PowerShell에서는:

$env:HASDATA_API_KEY = "your_key_here"; npm test

마지막 검사는 실제 호출을 수행하며 5크레딧이 소모됩니다. 이는 올바른 이유로 실패할 수 있는 카나리 검사로 볼 수 있습니다. 도구 목록 조회는 비어 있지 않은 키만 있으면 성공하며, 도구 목록만 확인하는 테스트는 키가 해제된 상태에서도 통과합니다.

기여하기

도구 표와 응답 샘플은 시간이 지나면서 어긋나기 쉬운 부분이므로, 이들에 대한 수정이 가장 유용한 기여입니다. 직접 호출한 내용과 받은 응답을 포함해 주세요. 포크에서 온 풀 리퀘스트는 키 없이 테스트 스위트를 실행하며, 실시간 검사는 실패 표시 대신 건너뜁니다.

라이선스

MIT. LICENSE를 참조하세요.