Google Maps API를 통해 AI 클라이언트가 장소 검색, 주소 지오코딩, 길 찾기, 경로 계획, 날씨 확인 및 로컬 순위 감사를 수행할 수 있게 합니다.
다른 이름 cablate/mcp-google-map, mcp-google-map, @cablate/mcp-google-map
- 스타
- 498
- Tools
- —
- 다운로드, 30일
- 4,556
- 최신 버전
- 0.0.69
- 마지막 커밋
- 2026년 10월 22일
- 라이선스
- MIT
Google Maps MCP란?
Google Maps은(는) MCP server입니다. Google Maps API를 통해 AI 클라이언트가 장소 검색, 주소 지오코딩, 길 찾기, 경로 계획, 날씨 확인 및 로컬 순위 감사를 수행할 수 있게 합니다.
프로젝트 README에서 생성된 요약
Google Maps MCP server 정보
개발자는 Google Maps Platform 기능을 통합하여 여행 일정 생성이나 로컬 검색 가시성 감사를 수행할 수 있습니다. 이 server는 18개의 읽기 전용 도구와 3개의 특화된 Skills를 제공하여, AI 에이전트가 단순한 단일 단계 조회를 넘어 복잡한 위치 기반 워크플로우를 수행할 수 있도록 합니다. 사용자는 Claude Desktop 또는 Cursor와 같은 로컬 데스크톱 클라이언트를 위한 stdio, 자동화를 위한 독립형 CLI, 또는 원격 배포를 위한 Streamable HTTP 설정 등 다양한 방식으로 이 기능에 접근할 수 있습니다.
server를 사용하려면 환경 변수, 명령줄 옵션 또는 HTTP 요청 헤더를 통해 Google Maps Platform API 키를 제공해야 합니다. 필요에 따라 Places API (New), Routes API 또는 Geocoding API와 같은 특정 API를 활성화해야 할 수도 있습니다. 시스템은 세밀한 제어를 지원하므로, GOOGLE_MAPS_ENABLED_TOOLS 설정을 사용하여 maps_geocode 또는 maps_directions와 같은 특정 도구만 등록함으로써 컨텍스트 제한을 관리할 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
Google Maps MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 Google Maps MCP 설치
$ claude mcp add --env 'GOOGLE_MAPS_API_KEY=<YOUR_GOOGLE_MAPS_API_KEY>' mcp-google-map -- npx -y @cablate/mcp-google-mapCursor에 Google Maps MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-google-map": {
"command": "npx",
"args": [
"-y",
"@cablate/mcp-google-map"
],
"env": {
"GOOGLE_MAPS_API_KEY": "<YOUR_GOOGLE_MAPS_API_KEY>"
}
}
}
}VS Code에 Google Maps MCP 설치
.vscode/mcp.json
{
"servers": {
"mcp-google-map": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@cablate/mcp-google-map"
],
"env": {
"GOOGLE_MAPS_API_KEY": "<YOUR_GOOGLE_MAPS_API_KEY>"
}
}
}
}VS Code CLI에 Google Maps MCP 설치
$ code --add-mcp '{"name":"mcp-google-map","type":"stdio","command":"npx","args":["-y","@cablate/mcp-google-map"],"env":{"GOOGLE_MAPS_API_KEY":"<YOUR_GOOGLE_MAPS_API_KEY>"}}'Claude Desktop에 Google Maps MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"mcp-google-map": {
"command": "npx",
"args": [
"-y",
"@cablate/mcp-google-map"
],
"env": {
"GOOGLE_MAPS_API_KEY": "<YOUR_GOOGLE_MAPS_API_KEY>"
}
}
}
}Codex에 Google Maps MCP 설치
$ codex mcp add mcp-google-map --env 'GOOGLE_MAPS_API_KEY=<YOUR_GOOGLE_MAPS_API_KEY>' -- npx -y @cablate/mcp-google-mapCodex config.toml에 Google Maps MCP 설치
~/.codex/config.toml
[mcp_servers.mcp-google-map] command = "npx" args = ["-y", "@cablate/mcp-google-map"] [mcp_servers.mcp-google-map.env] GOOGLE_MAPS_API_KEY = "<YOUR_GOOGLE_MAPS_API_KEY>"
Gemini CLI에 Google Maps MCP 설치
$ gemini mcp add -s user -e 'GOOGLE_MAPS_API_KEY=<YOUR_GOOGLE_MAPS_API_KEY>' mcp-google-map npx -- -y @cablate/mcp-google-mapGemini settings.json에 Google Maps MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"mcp-google-map": {
"command": "npx",
"args": [
"-y",
"@cablate/mcp-google-map"
],
"env": {
"GOOGLE_MAPS_API_KEY": "<YOUR_GOOGLE_MAPS_API_KEY>"
}
}
}
}구성
GOOGLE_MAPS_API_KEY필수비밀Google Maps API key (get one at https://console.cloud.google.com)
GOOGLE_MAPS_API_KEYGOOGLE_MAPS_ENABLED_TOOLSGOOGLE_MAPS_ENABLED_TOOLSComma-separated tool names to enable. Omit or * for all 18 tools.
| 이름 | 설명 | 유형 |
|---|---|---|
| GOOGLE_MAPS_API_KEY | Google Maps API key (get one at https://console.cloud.google.com) | 필수비밀 |
| GOOGLE_MAPS_API_KEY | — | |
| GOOGLE_MAPS_ENABLED_TOOLS | — | |
| GOOGLE_MAPS_ENABLED_TOOLS | Comma-separated tool names to enable. Omit or * for all 18 tools. |
자동 검사
2026년 11월 12일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능통과
- 오픈 소스 라이선스 (OSI)통과
- 최근 1년 내 커밋 또는 릴리스통과
- 패키지 이름이 인기 패키지와 유사하지 않음통과
- 원격 엔드포인트가 HTTPS 사용검사되지 않음
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 모델에 대한 숨겨진 지침 없음통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음통과
README
GitHub에서 보기Google Maps for AI agents
Stop rebuilding place search, routing, and location workflows for every AI app.
@cablate/mcp-google-map turns Google Maps Platform into 18 read-only agent tools and three focused Skills. An agent can find real places, verify routes, compare options, build practical itineraries, or audit local search visibility—through MCP or a standalone CLI.
You choose the integration model: Codex or Claude Code Plugin when you want Skills without MCP setup, stdio for desktop MCP clients, or Streamable HTTP for shared and remote deployments.
Why use it?
Giving an agent a raw Maps API is only the beginning. Useful answers often require several dependent calls: resolve a place, preserve its identity, search around it, check opening details, calculate travel time, and explain what was actually verified. This project packages that work into one consistent interface.
- Move from lookup to outcome. Atomic tools handle geocoding, place details, directions, weather, air quality, and maps. Composite tools explore areas, compare candidates, optimize stops, and measure local rankings.
- Use the same capabilities with or without MCP. The standalone
execCLI works with Agent Skills and automation; the MCP server exposes the same 18 tools over stdio or HTTP. - Give agents workflow guidance, not just function names. Three Skills cover general map research, evidence-backed travel planning, and local SEO. Codex loads their full instructions only when a request matches.
- Keep deployment and credentials under your control. Run locally or self-host. API keys remain in your environment or request headers, with per-session isolation for HTTP deployments.
- Start narrow and grow later. Register only the tools you need with
GOOGLE_MAPS_ENABLED_TOOLS, or use the full catalog.
What can an agent do?
| Outcome | How the project helps |
|---|---|
| Find and evaluate real places | Natural-language and nearby search, place details, ratings, hours, reviews, and distance comparison |
| Build a trip that works geographically | Candidate discovery, along-route stops, travel-time checks, multi-stop optimization, weather, and static maps |
| Research a neighborhood | Multi-category exploration plus targeted distance, elevation, timezone, weather, and air-quality checks |
| Plan field work or deliveries | Route matrices and optimized stop ordering for up to 25 stops |
| Audit local search visibility | Geographic grid ranking, competitor discovery, ARP, ATRP, and SoLV metrics |
| Enrich location data | Single or batch geocoding, reverse geocoding, and structured JSON output |
These are data and planning tools, not guarantees of safety, accessibility, opening status, or ranking outcomes. Applications displaying Places reviews, photos, or AI summaries must follow the content attribution and storage guidance.
Choose your integration
| Use | Best for | What runs |
|---|---|---|
| Codex Plugin | Asking Codex map, travel, or local SEO questions without MCP configuration | A matching Skill loads on demand and calls the standalone CLI |
| Claude Code Plugin | Installing the same three Skills from a Claude marketplace | Skills are namespaced under mcp-google-map and call the standalone CLI |
| Standalone CLI | Scripts, automation, and other Skill-compatible agents | One stateless command returns JSON |
| MCP stdio | Claude Desktop, Cursor, VS Code, and other local MCP clients | The client starts a local MCP process |
| Streamable HTTP | Multi-session, containerized, LAN, or remote access | A self-hosted server exposes /mcp |
All options require Node.js 22+ and a Google Maps Platform API key. Live calls may be billable. Enable the APIs needed by your selected tools; common place and route workflows require Places API (New), Routes API, and often Geocoding API.
Start with Codex—no MCP required
codex plugin marketplace add cablate/mcp-google-map --ref main
codex plugin add mcp-google-map@cablate
Set GOOGLE_MAPS_API_KEY in the environment where Codex runs, then start a new conversation. Verify the local setup without making a Google API request:
npx -y @cablate/mcp-google-map doctor
Success means the node, package, and api-key checks pass and live-api is skipped. Use doctor --live only when you intend to send potentially billable checks to Geocoding, Places, and Routes.
Try asking:
Plan a practical two-day Kyoto itinerary. Group nearby places, check travel times, and explain any opening-hour assumptions.
Codex selects google-maps for general location research, google-maps-travel-planning for itineraries, or google-maps-local-seo for business visibility analysis. The plugin does not register or start an MCP server. See the no-MCP walkthrough for a reproducible example.
Install in Claude Code—no MCP required
claude plugin marketplace add cablate/mcp-google-map
claude plugin install mcp-google-map@cablate-maps
Start a new Claude Code session, set GOOGLE_MAPS_API_KEY in its environment, and run the same doctor check shown above. Claude exposes the installed Skills with the plugin namespace, for example /mcp-google-map:google-maps-travel-planning.
Each GitHub release also includes a versioned mcp-google-map-claude-plugin-v*.zip and SHA-256 checksum for direct distribution. The release workflow builds this archive from the same skills/ source and validates it with Claude Code's official strict validator before publishing.
Use the standalone CLI
Every MCP tool also has a short CLI name:
npx -y @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'
npx -y @cablate/mcp-google-map exec search-places '{"query":"quiet cafes in Kyoto"}'
npx -y @cablate/mcp-google-map exec directions '{"origin":"Tokyo Station","destination":"Tokyo Skytree","mode":"transit"}'
Each call is stateless. Successful calls return { "success": true, "data": ... } on stdout; failures exit nonzero and write structured JSON to stderr.
For bulk address enrichment:
npx @cablate/mcp-google-map batch-geocode -i addresses.txt -o results.json
cat addresses.txt | npx @cablate/mcp-google-map batch-geocode -i -
Connect an MCP client
stdio
{
"mcpServers": {
"google-maps": {
"command": "npx",
"args": ["-y", "@cablate/mcp-google-map", "--stdio"],
"env": { "GOOGLE_MAPS_API_KEY": "YOUR_API_KEY" }
}
}
}
To reduce tool-list context, add a comma-separated allowlist such as "GOOGLE_MAPS_ENABLED_TOOLS": "maps_geocode,maps_directions,maps_search_places". Omit it or use * to expose all tools.
Streamable HTTP
npx @cablate/mcp-google-map --host 127.0.0.1 --port 3000 --apikey "YOUR_API_KEY"
{
"mcpServers": {
"google-maps": {
"type": "http",
"url": "http://127.0.0.1:3000/mcp"
}
}
}
Bind to 0.0.0.0 only when the server must accept external connections. For multi-tenant deployments, prefer the X-Google-Maps-API-Key request header so keys remain isolated by session.
Tool catalog
| Group | Tools |
|---|---|
| Places and discovery | maps_search_places, maps_search_nearby, maps_place_details, maps_explore_area, maps_compare_places, maps_search_along_route |
| Location and routing | maps_geocode, maps_reverse_geocode, maps_directions, maps_distance_matrix, maps_plan_route, maps_batch_geocode |
| Context and visualization | maps_elevation, maps_timezone, maps_weather, maps_air_quality, maps_static_map |
| Local SEO | maps_local_rank_tracker |
All 18 tools declare readOnlyHint: true and destructiveHint: false. Exact parameters, response shapes, and workflow recipes live in the tool reference.
API key and Google Cloud setup
The key must belong to a Google Cloud project with billing enabled and restrictions compatible with the runtime. The setup and diagnostics guide maps each capability to its required API and explains common failures.
Credential priority is:
X-Google-Maps-API-KeyHTTP request header--apikeycommand-line optionGOOGLE_MAPS_API_KEYenvironment variable
Prefer environment variables or request headers. Command-line secrets can appear in shell history and process listings.
Trust and limits
- Place and route facts come from the Google Maps Platform APIs enabled for your project; weather availability has regional limitations.
- A successful API response does not prove accessibility, safety, legal suitability, or real-time availability.
- The package preserves source and disclosure metadata where returned, but your interface remains responsible for compliant attribution and storage.
- HTTP mode supports per-session API-key isolation and DNS rebinding protection.
- This project is MIT licensed and self-hostable. See SECURITY.md for vulnerability reporting and Security Assessment Clarifications for the review checklist.
Development
git clone https://github.com/cablate/mcp-google-map.git
cd mcp-google-map
npm ci
npm run build
npm run test:unit
npm test
Live E2E calls require GOOGLE_MAPS_API_KEY and may be billable: npm run test:e2e.
Contributions are welcome. Read CONTRIBUTING.md before opening a pull request. Release history is in CHANGELOG.md.
Acknowledgements
Thanks to @junyinnnn for helping add Streamable HTTP support.
License
Google Maps MCP 질문
Google Maps MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add --env 'GOOGLE_MAPS_API_KEY=<YOUR_GOOGLE_MAPS_API_KEY>' mcp-google-map -- npx -y @cablate/mcp-google-map를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
Google Maps MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
Google Maps MCP server로 AI 에이전트가 무엇을 할 수 있나요?
장소 검색, 장소 상세 정보 조회, 주소 지오코딩, 경로 및 거리 행렬 계산, 다중 경유지 경로 계획을 수행할 수 있으며 날씨, 공기 질, 고도, 시간대 확인도 가능합니다. 또한 로컬 검색 가시성 감사 기능도 지원합니다.
Google Maps MCP server 인증은 어떻게 하나요?
GOOGLE_MAPS_API_KEY 환경 변수, --apikey 옵션 또는 X-Google-Maps-API-Key HTTP 헤더를 통해 Google Maps Platform API 키를 제공하면 됩니다.
이 Google Maps 도구들을 사용하려면 MCP가 반드시 필요한가요?
아니요. geocode, search-places, directions와 같은 짧은 서브 명령어를 사용하는 독립형 CLI를 통해서도 동일한 기능을 사용할 수 있으며, MCP server 없이 Skills를 로드하는 Codex 또는 Claude Code 플러그인을 통해서도 사용 가능합니다.
노출되는 Google Maps 도구를 제한할 수 있나요?
네. GOOGLE_MAPS_ENABLED_TOOLS를 쉼표로 구분된 허용 목록으로 설정하여 필요한 도구만 노출할 수 있습니다. 설정을 생략하거나 *를 사용하면 전체 카탈로그를 사용할 수 있습니다.
원격 또는 공유 용도로 Google Maps server를 HTTP로 실행할 수 있나요?
네. --host 및 --port 옵션으로 실행하면 /mcp 경로를 통해 Streamable HTTP로 MCP를 제공하며, 요청 헤더를 통해 세션별 API 키 격리를 지원합니다.