en es ja ko ru zh

google-maps-mcp

Name: google-maps-mcp
Author: apurvaumredkar

by apurvaumredkar

Overview Schema Related Servers Score Discussions

TypeScript

Remote

google-maps-mcp

LLM을 위한 도구로 Google Maps Platform API를 노출하는 TypeScript 기반 Model Context Protocol (MCP) 서버입니다. AI 어시스턴트에게 실제 구조화된 지도 데이터(길찾기, 대중교통 경로, 장소 검색, 주소 검증, 사진, 고도 등)를 제공하여 훈련 데이터에서 추측하는 대신 사용할 수 있게 합니다.

Claude Desktop 및 기타 MCP 호환 클라이언트와 작동합니다.

기능

세 가지 범주의 15개 도구:

카테고리	도구
지도	정적 지도 이미지 URL, 임베드 URL(iframe), 고도 데이터, Street View 이미지 URL
경로	턴바이턴 길안내(운전/도보/자전거/대중교통), 거리 행렬, 다중 경유지 경로 최적화
장소	지오코딩 / 역지오코딩, 장소 상세, 텍스트 검색, 주변 검색, 자동 완성, 사진, 주소 검증, 시간대

전송: HTTP Streamable(상태 저장 세션, SSE keep-alive) — 최신 MCP 전송 방식으로, mcp-remote 및 모든 HTTP 지원 클라이언트와 호환됩니다.

최소 의존성: 런타임 의존성은 @modelcontextprotocol/sdk와 zod 두 개뿐입니다. 모든 Google Maps 호출은 Node.js 내장 fetch를 통해 REST API를 사용하며 Google SDK가 필요 없습니다.

Related MCP server: google-maps-mcp-server

사전 요구사항

Node.js 22+ (또는 Docker)
mcp-remote — 전역으로 한 번 설치: npm install -g mcp-remote
관련 API가 활성화된 Google Maps Platform API 키 (아래 참조)
결제가 활성화된 Google Cloud 프로젝트

Google Cloud Console에서 활성화할 API

APIs & Services → Library로 이동하여 다음을 활성화하세요:

API	사용처
Maps Static API	`maps_static_map`
Street View Static API	`maps_street_view`
Maps Embed API	`maps_embed_url`
Elevation API	`maps_elevation`
Geocoding API	`places_geocode`
Time Zone API	`places_timezone`
Places API (New)	`places_details`, `places_text_search`, `places_nearby_search`, `places_autocomplete`, `places_photos`
Address Validation API	`places_address_validation`
Routes API	`routes_compute`, `routes_matrix`
Route Optimization API	`routes_optimize` (선택 사항)

프로덕션에서는 키를 이러한 API 및 서버 IP로 제한할 수 있습니다.

빠른 시작

옵션 A — Docker로 실행 (권장)

docker run -d \
  --name google-maps-mcp \
  -p 127.0.0.1:3003:3003 \
  -e GOOGLE_MAPS_API_KEY=your_key_here \
  -e MCP_AUTH_TOKEN=your_secret_token \
  ghcr.io/apurvaumredkar/google-maps-mcp:latest

확인:

curl http://localhost:3003/health
# {"status":"ok","service":"google-maps-mcp"}

옵션 B — npm / npx

설치 불필요 — npx로 바로 실행:

GOOGLE_MAPS_API_KEY=your_key_here \
MCP_AUTH_TOKEN=your_secret_token \
npx mcp-server-google-maps
# google-maps-mcp listening on port 3003

또는 전역으로 설치:

npm install -g mcp-server-google-maps
GOOGLE_MAPS_API_KEY=your_key_here MCP_AUTH_TOKEN=your_secret_token mcp-server-google-maps

기본 포트(3003)를 변경하려면 PORT=를 설정하세요.

옵션 C — 소스에서 빌드

git clone https://github.com/apurvaumredkar/google-maps-mcp.git
cd google-maps-mcp
npm install
npm run build

.env 파일을 생성하거나(또는 환경 변수를 내보내고):

GOOGLE_MAPS_API_KEY=your_key_here
MCP_AUTH_TOKEN=your_secret_token
# Optional — only needed for routes_optimize:
GOOGLE_CLOUD_PROJECT_ID=your_project_id

서버 시작:

GOOGLE_MAPS_API_KEY=... MCP_AUTH_TOKEN=... npm start
# google-maps-mcp listening on port 3003

옵션 D — Docker Compose (자체 호스팅 스택)

docker-compose.yml에 추가:

services:
  google-maps-mcp:
    build: .
    container_name: google-maps-mcp
    restart: unless-stopped
    ports:
      - "127.0.0.1:3003:3003"
    environment:
      - GOOGLE_MAPS_API_KEY=${GOOGLE_MAPS_API_KEY}
      - MCP_AUTH_TOKEN=${MCP_AUTH_TOKEN}
      - GOOGLE_CLOUD_PROJECT_ID=${GOOGLE_CLOUD_PROJECT_ID:-}

환경 변수

변수	필수	설명
`GOOGLE_MAPS_API_KEY`	예	Google Maps Platform API 키
`MCP_AUTH_TOKEN`	아니요	클라이언트가 `X-Api-Key` 헤더에 보내야 하는 비밀 토큰. 로컬 전용 사용 시 생략하고, 네트워크나 프록시를 통해 서버를 노출할 때 설정하세요. `openssl rand -hex 32`로 생성합니다.
`PORT`	아니요	HTTP 포트 (기본값: `3003`)
`GOOGLE_CLOUD_PROJECT_ID`	아니요	`routes_optimize`(Route Optimization API)에만 필요

클라이언트 연결

이 서버는 모든 MCP 호환 클라이언트와 함께 작동합니다 — Claude Desktop, LM Studio, Cursor 또는 Model Context Protocol을 지원하는 기타 도구. 클라이언트마다 구성 형식은 다를 수 있지만 엔드포인트와 인증은 동일합니다.

서버는 단일 엔드포인트를 제공합니다: POST/GET http://localhost:3003/mcp

MCP_AUTH_TOKEN이 설정된 경우 모든 요청에 다음 헤더를 포함해야 합니다:

X-Api-Key: <MCP_AUTH_TOKEN>

MCP_AUTH_TOKEN이 설정되지 않은 경우 헤더가 필요 없습니다(로컬 전용 사용에 적합).

Claude Desktop (예시)

~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json(Windows)을 편집하세요:

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3003/mcp",
        "--header",
        "X-Api-Key: your_secret_token"
      ]
    }
  }
}

도구 참조

지도

`maps_static_map` — 정적 지도 이미지

정적 지도의 직접 이미지 URL을 반환합니다.

매개변수	유형	기본값	설명
`center`	string	필수	주소 또는 `lat,lng`
`zoom`	integer	`13`	확대/축소 레벨 0–21
`size`	string	`640x480`	이미지 크기(픽셀 단위 WxH)
`maptype`	enum	`roadmap`	`roadmap` \| `satellite` \| `terrain` \| `hybrid`
`markers`	string	—	마커 사양(예: `color:red\|48.8566,2.3522`)
`path`	string	—	경로를 그리기 위한 경로 사양
`format`	enum	`png`	`png` \| `png8` \| `png32` \| `gif` \| `jpg`
`scale`	enum	`1`	`1` = 표준, `2` = HiDPI/레티나
`language`	string	—	라벨의 BCP 47 언어 코드
`region`	string	—	ISO 3166-1 alpha-2 지역 코드

`maps_embed_url` — 지도 임베드 URL

iframe에 사용할 수 있는 임베드 URL을 반환합니다.

매개변수	유형	설명
`mode`	enum	`place` \| `directions` \| `search` \| `view` \| `streetview`
`q`	string	장소/검색 쿼리(place, search 모드)
`center`	string	view/streetview 모드의 `lat,lng`
`zoom`	integer	확대/축소 레벨
`origin` / `destination`	string	directions 모드용
`waypoints`	string	세로 막대(	)로 구분된 경유지
`maptype`	enum	`roadmap` \| `satellite`

`maps_elevation` — 고도 데이터

해발 고도(미터)를 반환합니다.

매개변수	유형	설명
`locations`	string	세로 막대(	)로 구분된 `lat,lng` 쌍
`path`	string	세로 막대(	)로 구분된 `lat,lng` 경로
`samples`	integer	경로를 따라 샘플 수 (2–512)

`maps_street_view` — Street View 이미지

Street View 파노라마 이미지의 직접 URL을 반환합니다.

매개변수	유형	기본값	설명
`location`	string	—	주소 또는 `lat,lng`
`pano`	string	—	특정 파노라마 ID(위치 대체)
`size`	string	`640x480`	이미지 크기 WxH
`heading`	number	—	카메라 방향 0–360°
`pitch`	number	—	카메라 기울기 -90° ~ 90°
`fov`	number	`90`	시야각 10–120°
`source`	enum	—	실내 파노라마를 제외하려면 `outdoor`

매개변수	유형	기본값	설명
`origin`	string	required	주소 또는 `lat,lng`
`destination`	string	required	주소 또는 `lat,lng`
`travel_mode`	enum	`DRIVE`	`DRIVE` \| `WALK` \| `BICYCLE` \| `TRANSIT` \| `TWO_WHEELER`
`transit_allowed_modes`	enum[]	—	대중교통을 특정 차량 유형으로 필터링: `BUS` \| `SUBWAY` \| `TRAIN` \| `LIGHT_RAIL` \| `RAIL`. `travel_mode`가 `TRANSIT`인 경우에만 적용됩니다.
`intermediates`	string[]	—	출발지와 목적지 사이의 경유지(`TRANSIT`에서는 지원되지 않음)
`departure_time`	string	—	교통 상황을 반영한 경로 탐색을 위한 ISO 8601 날짜/시간
`avoid_tolls`	boolean	`false`	유료 도로 회피(`TRANSIT`에서는 지원되지 않음)
`avoid_highways`	boolean	`false`	고속도로 회피(`TRANSIT`에서는 지원되지 않음)
`avoid_ferries`	boolean	`false`	페리 회피(`TRANSIT`에서는 지원되지 않음)
`units`	enum	`METRIC`	`METRIC` \| `IMPERIAL`
`compute_alternative_routes`	boolean	`false`	최대 3개의 대안 경로 반환

`routes_matrix` — 경로 거리 행렬

여러 출발지와 목적지 간의 이동 시간/거리를 동시에 계산합니다.

매개변수	유형	기본값	설명
`origins`	string[]	required	최대 25개의 주소 또는 `lat,lng` 문자열
`destinations`	string[]	required	최대 25개의 주소 또는 `lat,lng` 문자열
`travel_mode`	enum	`DRIVE`	`DRIVE` \| `WALK` \| `BICYCLE` \| `TRANSIT`
`departure_time`	string	—	ISO 8601 날짜/시간
`units`	enum	`METRIC`	`METRIC` \| `IMPERIAL`

`routes_optimize` — 다중 경유지 경로 최적화

총 이동 거리를 최소화하도록 경유지 순서를 최적화합니다. GOOGLE_CLOUD_PROJECT_ID가 필요합니다.

매개변수	유형	설명
`vehicle_start`	string	시작 위치 — 반드시 `lat,lng`여야 함(필요 시 먼저 지오코딩)
`vehicle_end`	string	종료 위치(기본값은 시작 위치)
`visits`	object[]	`{ address, label?, duration_minutes? }` 배열 — 주소는 반드시 `lat,lng`여야 함
`travel_mode`	enum	`DRIVING` \| `WALKING`

장소

`places_geocode` — 지오코딩 / 역지오코딩

주소 ↔ 좌표 변환.

매개변수	유형	설명
`address`	string	지오코딩할 주소
`latlng`	string	역지오코딩용 `lat,lng`
`region`	string	ISO 3166-1 alpha-2 지역 편향
`components`	string	구성요소 필터 예: `country:FR\|postal_code:75001`

`places_details` — 장소 상세 정보

Google Place ID로 장소의 전체 상세 정보를 가져옵니다.

매개변수	유형	설명
`place_id`	string	Google Place ID
`fields`	string	쉼표로 구분된 필드 마스크(합리적인 기본값 있음)
`language_code`	string	응답 언어

`places_text_search` — 텍스트로 장소 검색

자연어 쿼리와 일치하는 장소를 찾습니다.

매개변수	유형	설명
`query`	string	예: `"best ramen in Tokyo"`
`location_bias_lat/lng`	number	이 위치를 기준으로 결과 편향
`location_bias_radius_m`	number	편향 원 반경
`max_results`	integer	1–20, 기본값 10
`min_rating`	number	최소 평균 별점(0–5)
`open_now`	boolean	현재 영업 중인 장소만
`included_type`	string	장소 유형으로 필터링 예: `restaurant`
`price_levels`	enum[]	`PRICE_LEVEL_FREE` … `PRICE_LEVEL_VERY_EXPENSIVE`

`places_nearby_search` — 주변 장소 검색

좌표 반경 내의 주변 장소를 찾습니다.

매개변수	유형	설명
`latitude` / `longitude`	number	검색 중심
`radius_m`	number	미터 단위 검색 반경(최대 50,000)
`included_types`	string[]	장소 유형 필터
`excluded_types`	string[]	제외할 장소 유형
`max_results`	integer	1–20, 기본값 10
`rank_preference`	enum	`DISTANCE` \| `POPULARITY`

`places_autocomplete` — 장소 자동 완성

부분 입력으로 장소 이름을 예측합니다.

매개변수	유형	설명
`input`	string	완성할 부분 텍스트
`location_bias_lat/lng`	number	이 위치 기준 편향
`included_primary_types`	string[]	유형 필터
`country_codes`	string[]	ISO 3166-1 alpha-2 국가 필터
`include_query_predictions`	boolean	쿼리 예측도 반환

`places_photos` — 장소 사진

장소의 사진 URL을 가져옵니다.

매개변수	유형	기본값	설명
`place_id`	string	required	Google Place ID
`max_photos`	integer	`3`	반환할 최대 사진 수(1–10)
`max_width_px`	integer	`1200`	최대 사진 너비(픽셀)
`max_height_px`	integer	`900`	최대 사진 높이(픽셀)

`places_address_validation` — 주소 검증

우편 주소를 검증하고 표준화합니다.

매개변수	유형	설명
`address_lines`	string[]	주소 줄
`region_code`	string	ISO 3166-1 alpha-2 국가 코드
`locality`	string	시/군
`administrative_area`	string	주/도
`postal_code`	string	우편번호
`enable_usps_cass`	boolean	USPS CASS 검증(미국만)

`places_timezone` — 시간대 가져오기

모든 좌표에 대한 IANA 시간대 및 UTC/DST 오프셋을 가져옵니다.

매개변수	유형	설명
`latitude` / `longitude`	number	위치
`timestamp`	integer	DST 계산용 Unix 타임스탬프(기본값은 현재 시간)
`language`	string	응답 언어

아키텍처

src/
├── index.ts         # Raw Node.js HTTP server, auth, stateful session management
├── server.ts        # McpServer instantiation + tool registration
├── maps-client.ts   # Typed fetch wrappers for all Google Maps REST APIs
└── tools/
    ├── maps.ts      # 4 tools: static map, embed, elevation, street view
    ├── routes.ts    # 3 tools: compute route, matrix, optimize
    └── places.ts    # 8 tools: geocode, details, text search, nearby, autocomplete,
                     #          photos, address validation, timezone

주요 설계 결정:

Express 대신 원시 node:http — MCP SDK 내부의 Hono 기반 요청 처리와의 올바른 상호 운용을 위해 필요. Express는 요청 본문 스트림을 미리 소비하여 StreamableHTTPServerTransport를 깨뜨립니다.
상태 저장 세션 맵 — mcp-remote와 SSE keep-alive는 요청 간에 세션이 유지되어야 합니다. 세션은 Mcp-Session-Id 헤더를 키로 사용하며 전송 종료 시 정리됩니다.
본문 읽기 전 인증 — X-Api-Key 검사는 본문 스트림을 건드리기 전에 헤더에서 수행되므로 거부된 요청은 깔끔하게 소진됩니다.
Google API 인증 분리 — 레거시 REST API(Static Maps, Geocoding, Elevation, Timezone, Street View)는 ?key= 쿼리 매개변수를 사용하고, 신규 API(Places v1, Routes v2, Address Validation)는 X-Goog-Api-Key 헤더를 사용합니다.

개발

npm run dev    # TypeScript watch mode (tsc --watch)
npm run build  # Compile to dist/
npm start      # Run compiled server

변경 사항 반영 후 Docker 이미지 다시 빌드

docker compose build google-maps-mcp
docker compose up -d google-maps-mcp

MCP 엔드포인트 테스트

# Health check (no auth required)
curl http://localhost:3003/health

# MCP initialize (auth required)
TOKEN=your_secret_token
curl -s -X POST http://localhost:3003/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Api-Key: $TOKEN" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1"}},"id":1}'

# List tools (use session ID from Mcp-Session-Id response header)
SESSION=<Mcp-Session-Id from above>
curl -s -X POST http://localhost:3003/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Api-Key: $TOKEN" \
  -H "Mcp-Session-Id: $SESSION" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":2}'

Windows/WSL 주의사항: .env 파일에 Windows CRLF 줄 바꿈이 있는 경우 tr -d '\r'로 값을 추출하세요:
TOKEN=$(grep MCP_AUTH_TOKEN .env | cut -d= -f2 | tr -d '\r')

변경 로그

v1.0.4

routes_compute: TRANSIT 모드에 대한 사전 검증 추가 — intermediates 또는 경로 수정자(avoid_tolls, avoid_highways, avoid_ferries)를 전달하면 Google API의 불명확한 400 오류 대신 명확하고 실행 가능한 오류를 반환합니다.

v1.0.3

routes_compute: 차량 유형(BUS, SUBWAY, TRAIN, LIGHT_RAIL, RAIL)별로 대중교통 경로를 필터링하는 transit_allowed_modes 매개변수 추가.

v1.0.2

지도, 경로, 장소 카테고리에 걸친 15개 도구로 최초 공개 릴리스.

This server cannot be installed

license - permissive license

Not graded

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

2wRelease cycle

3Releases (12mo)

Commit activity

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

MCP Google Map Server
Location Services
cablate
A
license
B
quality
A
maintenance
A Model Context Protocol server that provides Google Maps API integration, allowing users to search locations, get place details, geocode addresses, calculate distances, obtain directions, and retrieve elevation data through LLM processing capabilities.
Updated 7 days ago (2026-08-16 12:55 UTC)
7
1,992
428
MIT
google-maps-mcp-server
Location Services Travel & Transportation
ettysekhon
A
license
A
quality
D
maintenance
Production-ready MCP server for Google Maps Platform APIs, providing 11 tools for directions, places, geocoding, traffic, and road data to empower AI agents with location intelligence.
Updated 6 months ago (2026-03-01 18:48 UTC)
11
4
Apache 2.0
Swagger MCP Adapter
Developer Tools AI & Machine Learning Documentation Access
serifcolakel
A
license
A
quality
D
maintenance
A TypeScript-based MCP server that integrates with Swagger/OpenAPI specifications to expose API endpoints as tools for Large Language Models (LLMs), enabling natural language interaction with any OpenAPI-compliant API.
Updated 6 months ago (2026-03-01 13:26 UTC)
4
9
MIT
google-maps-comprehensive-mcp
Location Services Travel & Transportation
vicpeacock
F
license
Not graded
quality
D
maintenance
Comprehensive MCP server for Google Maps APIs, enabling geocoding, place search and details, distance matrix, elevation, and directions through natural language.
Updated a year ago (2025-09-27 07:12 UTC)
6

View all related MCP servers

Related MCP Connectors

Google Maps Scraper
Live Google Maps business search, review, and photo data for AI agents over MCP.
Google_maps
Google Maps MCP Pack — geocoding, places, directions, distance matrix, elevation.
microservices.sh
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.

View all MCP Connectors

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/apurvaumredkar/google-maps-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

google-maps-mcp

기능

사전 요구사항

Google Cloud Console에서 활성화할 API

빠른 시작

옵션 A — Docker로 실행 (권장)

옵션 B — npm / npx

옵션 C — 소스에서 빌드

옵션 D — Docker Compose (자체 호스팅 스택)

환경 변수

클라이언트 연결

Claude Desktop (예시)

도구 참조

지도

maps_static_map — 정적 지도 이미지

maps_embed_url — 지도 임베드 URL

maps_elevation — 고도 데이터

maps_street_view — Street View 이미지

routes_matrix — 경로 거리 행렬

routes_optimize — 다중 경유지 경로 최적화

장소

places_geocode — 지오코딩 / 역지오코딩

places_details — 장소 상세 정보

places_text_search — 텍스트로 장소 검색

places_nearby_search — 주변 장소 검색

places_autocomplete — 장소 자동 완성

places_photos — 장소 사진

places_address_validation — 주소 검증

places_timezone — 시간대 가져오기

아키텍처

개발

변경 사항 반영 후 Docker 이미지 다시 빌드

MCP 엔드포인트 테스트

변경 로그

v1.0.4

v1.0.3

v1.0.2

Maintenance

Resources

Looking for Admin?

Related MCP Servers

MCP Google Map Server

google-maps-mcp-server

Swagger MCP Adapter

google-maps-comprehensive-mcp

Related MCP Connectors

Latest Blog Posts

MCP directory API

`maps_static_map` — 정적 지도 이미지

`maps_embed_url` — 지도 임베드 URL

`maps_elevation` — 고도 데이터

`maps_street_view` — Street View 이미지

`routes_matrix` — 경로 거리 행렬

`routes_optimize` — 다중 경유지 경로 최적화

`places_geocode` — 지오코딩 / 역지오코딩

`places_details` — 장소 상세 정보

`places_text_search` — 텍스트로 장소 검색

`places_nearby_search` — 주변 장소 검색

`places_autocomplete` — 장소 자동 완성

`places_photos` — 장소 사진

`places_address_validation` — 주소 검증

`places_timezone` — 시간대 가져오기