1. 项目概述为你的AI助手装上“地图大脑”如果你经常和Claude、Cursor这类AI助手打交道可能会发现一个痛点当对话涉及到具体的地理位置、路线规划或者周边探索时AI的回答往往停留在“我知道这个概念”的层面无法给出实时、精确、可操作的信息。比如你问“公司附近有没有适合下午茶的咖啡馆”它可能只能泛泛而谈却无法告诉你步行5分钟就有一家评分4.8的精品店。gmaps-mcp这个项目就是为了彻底解决这个问题而生的。它是一个基于Model Context Protocol的服务器简单来说它在你本地的AI助手和Google Maps庞大的实时数据库之间架起了一座高速桥梁。通过它你的Claude Desktop、Cursor或者Claude Code就能像调用一个内置函数一样直接查询Google Maps的所有核心功能。这个项目的核心价值在于“原生集成”和“零配置复杂度”。它不是一个需要你写大量胶水代码的SDK也不是一个笨重的中间件。你只需要一条安装命令加上一个API密钥你的AI助手就瞬间获得了“地图视野”。无论是寻找附近的餐厅、查询地点的详细评分与营业时间、规划从A点到B点的最佳路线还是进行地址与坐标的互转现在都可以通过自然语言对话直接完成。它适合所有希望提升AI助手实用性的开发者、产品经理乃至普通用户。如果你厌倦了在聊天窗口和地图App之间反复切换或者你正在构建的AI应用需要地理空间智能那么gmaps-mcp就是你工具箱里缺失的那块拼图。接下来我会带你从零开始深入拆解它的工作原理、部署细节并分享我在集成和使用过程中积累的一手经验。2. 核心设计思路为什么是MCP以及它如何工作在深入代码之前理解Model Context Protocol的设计哲学至关重要。MCP不是一个新奇的网络协议它的目标非常明确为AI模型提供一个标准化、可扩展的“感官”和“手脚”接口。你可以把它想象成电脑的USB协议——定义了设备如何与主机通信至于这个设备是键盘、U盘还是摄像头协议本身并不关心。gmaps-mcp正是这样一个符合MCP标准的“外设”。它的设计思路可以概括为以下几点2.1 协议抽象而非应用封装很多项目尝试把Google Maps API封装成一个库然后让你在代码里调用。gmaps-mcp的思路更高一层它把自己变成一个服务。这个服务通过MCP协议向AI客户端如Claude暴露一组定义良好的工具。AI客户端不需要理解HTTP请求、API密钥管理或JSON解析它只需要按照MCP的格式“告诉”服务器“用户想搜索咖啡店”服务器就会处理好一切并返回结构化的结果。这种设计的最大好处是解耦。Google Maps API的迭代、认证方式的变化甚至未来替换成其他地图服务商这些复杂性都被封装在MCP服务器内部。对AI客户端和使用者来说交互界面始终是稳定、自然的对话。2.2 双传输层支持兼顾本地与远程场景这是gmaps-mcp一个非常务实且出色的设计。它同时支持两种运行模式Stdio模式这是为Claude Desktop、Cursor等本地桌面AI客户端量身定做的。MCP客户端如Claude直接通过标准输入/输出stdio启动并调用这个服务器进程。所有通信都在你本地机器上进行延迟极低数据不出本地隐私性和响应速度都得到保障。这是个人使用的首选模式。HTTP模式服务器作为一个独立的Web服务运行。这开启了全新的可能性团队共享团队可以部署一个中央gmaps-mcp服务器所有成员配置自己的AI客户端指向它无需每人申请和管理API密钥。A2A场景你的一个AI Agent可以调用另一个部署了gmaps-mcp的Agent来获取地理信息实现智能体间的协作。混合云部署你可以将服务器部署在离用户或数据源更近的云服务器上优化网络延迟。同一个代码库通过不同的入口点__main__.py和run.py来适配这两种模式保证了功能的一致性也极大地扩展了应用场景。2.3 工具设计的语义化与完整性项目没有选择只实现最常用的“搜索”功能而是完整实现了Google Maps Platform最核心的六大能力并将其映射为六个语义清晰的“工具”search_places: 语义搜索。对应人类“找东西”的直觉。get_place_details: 深度信息获取。对应人类“了解更多”的需求。search_nearby: 基于位置的半径搜索。对应“我在这里附近有什么”的场景。get_directions: 路径规划。对应“怎么去”的核心问题。geocode/reverse_geocode: 地址与坐标的互转。这是所有空间计算的基础。这六个工具几乎覆盖了90%以上的日常地图查询需求。更重要的是它们的命名和参数设计非常直观使得AI模型能很容易地理解在什么情境下该调用哪个工具。例如当用户说“故宫的坐标是多少”AI会自然地调用geocode而当用户说“我在这提供坐标附近有药店吗”AI则会组合使用reverse_geocode先确认位置和search_nearby。实操心得工具命名的艺术在设计和实现MCP工具时命名至关重要。一个好的工具名如search_nearby应该让AI模型能直接从自然语言中推断出其用途。避免使用过于技术化的缩写或内部代号。gmaps-mcp在这点上做得很好它的工具名几乎就是一句简短的英文描述极大降低了AI模型的理解和调用门槛。3. 从零开始部署与配置详解理论讲完了我们上手实操。我会假设你是一个全新的用户从获取API密钥到在Claude Desktop中成功使用一步步带你走通并穿插我踩过的坑和总结的技巧。3.1 获取并配置Google Maps API密钥这是整个流程中唯一有“门槛”的步骤但按照指引操作十分钟内一定能完成。第一步创建或选择Google Cloud项目访问 Google Cloud Console 。如果你是新用户会提示你创建项目。给它起个名字比如my-ai-maps。如果你已有项目在顶部的项目下拉菜单中选择一个。第二步启用账单最关键且最容易出错的一步这是新手最大的拦路虎。Google Maps API即使有免费额度也必须关联一个已启用账单的账户。在左侧导航栏找到“结算”。如果你还没有结算账户按照提示创建一个并关联信用卡。请放心新用户会获得每月200美元的免费赠金绝大多数个人开发者的用量远低于此不会产生费用。返回项目概览页确保页面顶部显示“结算已启用”。避坑指南403 BILLING_DISABLED 错误我见过无数开发者卡在这一步。症状是API密钥配置正确但调用时返回403错误提示BILLING_DISABLED。100%的原因就是忽略了这一步。即使你看到了“免费额度”的说明也必须先启用账单。启用后可能需要等待2-5分钟Google的系统才能完全生效。第三步启用所需API在左侧导航栏进入“API和服务” → “库”。 在搜索框中依次搜索并启用以下三个APIPlaces API (New)这是新一代的 Places APIsearch_places,get_place_details,search_nearby都依赖它。Directions API为get_directions提供路径规划能力。Geocoding API为geocode和reverse_geocode提供坐标转换服务。第四步创建并限制API密钥进入“API和服务” → “凭据”。点击“创建凭据”→“API密钥”。系统会生成一个密钥。强烈建议立即点击这个新创建的API密钥进行编辑。在“API限制”部分选择“限制密钥”。在下拉菜单中仅勾选你刚才启用的那三个APIPlaces API (New),Directions API,Geocoding API。然后点击保存。安全提示密钥限制永远不要使用无限制的API密钥。如果你的密钥泄露攻击者可以用它调用任何Google Cloud API可能导致巨额账单。将其严格限制在必要的API上是成本控制和安全防护的第一道防线。gmaps-mcp只需要这三个API所以只勾选这三个。至此你的API密钥一串以AIza开头的长字符串已经准备就绪。复制它我们接下来会用到。3.2 安装uv工具gmaps-mcp推荐使用uv来安装和运行。uv是一个用Rust写的极速Python包管理器和运行器比传统的pip快得多并且完美解决了依赖隔离问题。在macOS或Linux上安装打开终端运行curl -LsSf https://astral.sh/uv/install.sh | sh安装完成后重启你的终端或者运行source ~/.bashrc(或source ~/.zshrc) 使uv命令生效。在Windows上安装在PowerShell管理员身份中运行powershell -c irm https://astral.sh/uv/install.ps1 | iex验证安装uv --version应该能显示版本号。3.3 配置Claude Desktop这是最常用的场景。Claude Desktop内置了MCP客户端支持配置非常直观。打开Claude Desktop应用。点击左下角的你的头像进入“设置”。在设置窗口中找到并点击“开发者”标签页。点击“编辑配置”按钮。这会打开一个JSON配置文件通常是claude_desktop_config.json。在配置文件中你需要添加一个mcpServers字段如果不存在的话。最终的配置结构如下{ mcpServers: { google-maps: { command: uvx, args: [gmaps-mcp], env: { GOOGLE_MAPS_API_KEY: 你的_API_密钥_粘贴在这里 } } } }配置解析google-maps: 这是你给这个服务器起的名字可以自定义但建议保持一致。command: uvx: 告诉Claude使用uvx命令来运行。uvx是uv的一部分用于直接从网络运行Python工具无需先pip install。args: [gmaps-mcp]: 传递给uvx的参数即要运行的包名。uvx会自动从PyPI下载gmaps-mcp包并执行。env: 设置环境变量。这里将你的Google Maps API密钥传递给服务器进程。保存配置文件并完全关闭Claude Desktop应用。重新启动Claude Desktop。验证安装重启后当你开始一个新的对话时如果配置成功Claude的回复会显得更“聪明”。你可以直接测试“帮我找找旧金山唐人街附近评价最高的中餐馆。” 如果Claude开始调用工具你会看到它正在“思考”的提示然后给出结构清晰、带有具体地址、评分和营业时间的结果。3.4 配置CursorCursor的配置与Claude Desktop类似但配置文件路径不同。Cursor的MCP配置文件位于~/.cursor/mcp.jsonmacOS/Linux或%USERPROFILE%\.cursor\mcp.jsonWindows。用文本编辑器打开或创建这个文件。添加与Claude Desktop类似的配置{ mcpServers: { google-maps: { command: uvx, args: [gmaps-mcp], env: { GOOGLE_MAPS_API_KEY: 你的_API_密钥_粘贴在这里 } } } }保存文件并重启Cursor。在Cursor的聊天窗口中同样可以开始测试地理查询。3.5 配置Claude CodeClaude Code主要通过命令行工具claude进行管理。确保你已安装Claude Code CLI工具。在终端中执行以下命令claude mcp add google-maps \ -e GOOGLE_MAPS_API_KEY你的_API_密钥_粘贴在这里 \ -- uvx gmaps-mcp这条命令直接完成了配置的添加。你可以通过claude mcp list来查看已配置的MCP服务器确认google-maps在列表中。4. 六大工具深度解析与实战技巧配置成功后你的AI助手就拥有了六把“地理空间瑞士军刀”。下面我们逐一深入每个工具了解它们的能力边界、最佳使用场景和我总结的实战技巧。4.1search_places: 你的万能地点搜索器这是最常用、最强大的工具。它本质上是对Google Maps搜索框的API化。核心参数与能力query: 支持自然语言。从“附近的加油站”到“纽约有户外座位的、适合工作的咖啡馆”都可以。返回字段极其丰富不仅仅是名字和地址还包括电话、网站、Google Maps链接、评分、评论数、价格等级$-$$$$、类型标签、实时营业状态、详细的每周营业时间以及营业状态。实战技巧与注意事项查询的艺术越具体结果越精准。“咖啡”可能返回星巴克“第三波浪潮 手冲 咖啡 旧金山”则更可能找到精品店。合理使用地点限定词如“在北京”、“near Central Park”能有效过滤结果。理解business_status这个字段非常重要它能告诉你地点是OPERATIONAL营业中、CLOSED_TEMPORARILY暂时关闭还是CLOSED_PERMANENTLY永久关闭。在为用户做推荐时优先过滤掉非运营状态的地点。price_level的使用1-4级分别对应$到$$$$。在为用户筛选时这是一个很好的过滤维度。例如“找一家$$左右的意大利餐厅。”结果数量限制Google Places API每次查询默认返回最多20个结果并且有分页机制。gmaps-mcp的封装应该会处理合理的默认值但如果你需要大量结果可能需要多次查询或使用分页令牌如果工具支持。示例对话用户“我想周末去爬山帮我找找洛杉矶附近风景好的、难度中等的徒步路线起点最好有停车场和卫生间。” AI思考这需要将“徒步路线起点”转化为地点搜索。可能会构造查询如“trailhead parking restrooms Los Angeles”。然后从结果中筛选类型包含“park”或“tourist_attraction”并在回复中重点提及name,address,rating, 以及types中是否有parking和restroom相关的暗示虽然API可能不直接返回这些设施作为独立字段但可以从用户评论或描述中推断。4.2get_place_details: 从概览到深度情报当你通过search_places找到一个感兴趣的地点后get_place_details就是你的深度侦察工具。它需要上一个工具返回的place_id。核心价值用户评论获取最新的、带评分的用户评论了解真实口碑。编辑摘要Google官方提供的简短描述通常很精炼。便利设施标志这是黄金信息包括delivery外卖、dine_in堂食、takeout自取、reservable可预订、outdoor_seating户外座位、live_music现场音乐等布尔值。对于餐厅、咖啡馆等场所这些信息至关重要。支付选项和无障碍设施payment_options和accessibility_options提供了更细致的服务信息。实战技巧组合使用典型的流程是search_places→ 用户选择 →get_place_details。在AI对话中你可以让AI先给出一个精简的列表然后问用户“你对‘XXX咖啡馆’感兴趣吗我可以为你查看它的详细评论和是否有户外座位。”缓存place_id如果你在构建一个连续对话的AI应用在上下文中缓存已提及地点的place_id可以避免用户需要重复说出完整名称体验更流畅。评论处理API通常只返回最相关的几条评论。注意评论的relative_time_description如“一个月前”优先参考更新近的评论。4.3search_nearby: 基于地理围栏的精准发现这个工具用于回答“我在这里周围X米内有什么”这类问题。它不依赖文本关键词而是纯粹基于经纬度和半径进行地理过滤。核心参数latitude,longitude: 中心点坐标。通常来自geocode的结果或用户直接提供。radius_meters: 搜索半径最大值是50000米50公里。不要试图设置得过大精确的小范围搜索效果更好。place_type(可选): 按类型过滤。如restaurant,cafe,bank,hospital。使用类型过滤可以大幅提升结果的相关性。实战技巧与geocode联动这是最常见的模式。用户说“我在外滩附近有咖啡馆吗”。AI应先调用geocode(“外滩”)获取坐标再调用search_nearby。半径选择在城市中心500米半径可能就有上百个结果在郊区可能需要2000米。可以根据对话上下文和地点类型动态建议。例如“你要找便利店通常较多我搜索500米内。你要找宠物医院相对较少我搜索2000米内。”类型过滤的威力Google Places API支持丰富的类型列表。在医疗紧急情况下place_type: “hospital”或“pharmacy”能快速定位关键设施。4.4get_directions: 多模态路径规划引擎从A到B怎么走这个工具给出了答案并支持四种出行方式。核心参数origin,destination: 起点和终点。可以是地址字符串也可以是“lat,lng”格式的坐标。坐标优先因为地址解析可能有歧义。mode:driving驾车默认、walking步行、bicycling骑行、transit公共交通。不同模式返回的路线和时间差异巨大。返回信息解析routes: 可能返回多条备选路线。legs: 一条路线可能包含多个路段如需要换乘。steps: 每个路段内的详细转向指示。这是生成人类可读导航说明的基础。duration_in_traffic: 仅在驾车模式下提供基于实时路况的预估时间。这个信息价值很高。实战技巧出行方式建议AI可以根据距离和常识建议模式。例如距离2公里建议步行在城市中心拥堵时段建议对比驾车和公共交通的时间。结构化输出API返回的是结构化的steps。AI在回复时应该将其转化为更自然的语言例如“首先从Union Square向西走到Powell Street大约200米。然后右转进入Powell Street继续走300米...全程步行约10分钟。”时间上下文driving模式的duration_in_traffic是动态的。在回复时可以加上“根据当前路况”的说明让用户知道这个时间是实时的。4.5geocode与reverse_geocode: 空间与文字的桥梁这两个是基础但必不可少的工具。geocode: 将人类可读的地址或地名转换为精确的坐标经纬度。这是几乎所有空间计算的起点。地址越完整解析越准确。“北京市海淀区”可能返回一个大致区域中心而“北京市海淀区丹棱街5号”则返回精确点。reverse_geocode: 将坐标转换回人类可读的地址。它返回的是结构化的address_components包含国家、省/州、城市、街道等不同层级的信息。你可以用它来回答“这是哪里”或者从坐标中提取城市名、街区名。实战技巧处理歧义geocode“Paris”可能返回法国巴黎也可能是美国德州的巴黎。如果对话上下文有位置暗示例如之前提到过“欧洲旅行”AI应优先选择更相关的那个结果或者在不确定时向用户确认。坐标格式确保传递给其他工具如search_nearby的坐标格式是float类型的latitude和longitude而不是字符串。location_type:geocode返回的location_type字段表示匹配精度如ROOFTOP精确到门牌、RANGE_INTERPOLATED街道插值、APPROXIMATE近似如城市级别。了解这个有助于评估结果的可靠性。5. 高级部署模式HTTP服务器与远程访问虽然Stdio模式适合个人但HTTP服务器模式才是发挥gmaps-mcp全部威力的地方。它让你可以构建一个共享的、可远程访问的地理智能服务。5.1 本地启动HTTP服务器首先你需要克隆项目源码而不是直接用uvx运行。# 1. 克隆仓库 git clone https://github.com/arthurkatcher/google-maps-mcp cd google-maps-mcp # 2. 使用uv创建虚拟环境并安装依赖uv sync相当于 pip install -e . uv sync # 3. 复制环境变量示例文件并配置你的API密钥 cp .env.example .env # 使用文本编辑器打开 .env 文件填入你的 GOOGLE_MAPS_API_KEY # GOOGLE_MAPS_API_KEY你的_密钥_在这里 # 4. 启动HTTP服务器 uv run python run.py服务器默认会在http://0.0.0.0:8000启动。你可以访问http://localhost:8000/health来检查服务是否健康运行。5.2 配置认证可选但推荐.env文件中的MCP_API_KEY变量用于设置服务器端认证。如果你打算将服务暴露到公网务必设置此变量。# 在 .env 文件中 GOOGLE_MAPS_API_KEY你的_Google_Maps_密钥 MCP_API_KEY你自己设定的一个强密码例如一个长的随机字符串设置后客户端在连接时必须在HTTP头中提供X-API-Key: 你自己设定的密码。5.3 使用ngrok进行内网穿透测试你可以在本地测试远程连接。使用ngrok工具可以轻松创建一个临时的公网URL指向你本地的服务器。# 假设你的服务器运行在8000端口 ngrok http 8000ngrok会生成一个类似https://abcd1234.ngrok-free.dev的URL。任何能访问互联网的MCP客户端都可以通过这个URL连接到你的gmaps-mcp服务器。5.4 配置远程客户端以Claude Desktop为例你需要修改配置从使用本地命令uvx改为连接远程HTTP服务器。修改claude_desktop_config.json:{ mcpServers: { google-maps-remote: { // 名字可以自定义 url: https://你的-ngrok-地址.ngrok-free.dev/mcp/, headers: { X-API-Key: 你在.env中设置的MCP_API_KEY // 如果设置了认证 } } } }关键点url必须指向/mcp/端点这是MCP协议的标准端点。如果服务器设置了MCP_API_KEY则必须在headers中提供。重启Claude Desktop后它就会通过互联网与你本地的服务器通信。5.5 生产环境部署考量对于团队或生产环境你可能会将gmaps-mcp部署在云服务器如AWS EC2、Google Cloud Run、Railway等上。环境变量管理使用云平台提供的Secrets Manager或环境变量配置来安全地存储GOOGLE_MAPS_API_KEY和MCP_API_KEY。进程管理使用systemd(Linux)、supervisord或 Docker容器来确保服务器进程常驻并在崩溃时自动重启。反向代理与SSL使用Nginx或Caddy作为反向代理处理SSL/TLS终止HTTPS并提供额外的安全层和负载均衡如果需要。监控与日志确保服务器日志被收集例如发送到Stdout由Docker或云日志服务捕获并监控服务器的健康状态/health端点。成本监控虽然免费额度很高但仍建议在Google Cloud Console中为你的项目设置预算提醒以防意外的高频调用。6. 常见问题排查与性能优化实录即使按照指南操作也难免会遇到问题。下面是我在部署和使用过程中遇到的一些典型问题及解决方案。6.1 问题排查速查表问题现象可能原因解决方案Claude/Cursor无反应不调用地图工具1. MCP配置错误2. 服务器进程启动失败1. 检查JSON配置文件格式确保无语法错误。2. 在终端手动运行uvx gmaps-mcp看是否有错误输出如API密钥无效。3. 重启AI客户端。调用工具后返回403 BILLING_DISABLEDGoogle Cloud项目未启用账单登录Google Cloud Console为项目启用结算功能并等待几分钟后重试。调用工具后返回API_KEY_INVALID或API not enabled1. API密钥错误2. 所需API未启用1. 核对API密钥是否复制正确无多余空格。2. 在GCP控制台确认Places API (New)、Directions API、Geocoding API已启用。3. 确认API密钥已限制在这三个API上。错误信息包含uvx: command not founduv工具未安装或未在PATH中按照本文“安装uv工具”章节重新安装并确保终端重启或source了配置文件。HTTP模式服务器启动失败提示端口占用端口8000已被其他程序使用修改run.py中的端口号或使用uv run python run.py --port 8080如果脚本支持参数。远程客户端连接HTTP服务器超时1. 服务器未运行2. 防火墙/网络问题3. ngrok隧道中断1. 在服务器本地用curl localhost:8000/health测试。2. 检查服务器防火墙是否放行了8000端口。3. 重启ngrok更新客户端配置中的URL。搜索返回结果很少或不相关1. 查询词太宽泛2. 地点类型不匹配3. 区域限制1. 使用更具体、包含地点和特征的关键词。2. 尝试使用search_nearby并指定place_type。3. 注意某些Google服务在某些国家/地区可能受限。6.2 性能优化与成本控制心得1. 缓存是王道Google Maps API调用有延迟通常100-500ms且计入配额。对于相对静态的信息如地点的坐标、电话号码、基本详情可以在你的应用层或MCP服务器层添加缓存。例如将geocode的结果地址-坐标缓存一段时间如24小时可以极大减少重复调用。2. 合理设置超时与重试网络可能不稳定。在HTTP服务器模式下确保你的客户端设置了合理的连接超时和读取超时例如10秒。对于非关键查询可以考虑实现简单的重试逻辑最多1-2次。3. 理解免费配额避免浪费每月200美元的免费额度听起来很多但也要心中有数Places API (New): 约 $17.00 / 1000 次调用。Geocoding/Directions API: 约 $5.00 / 1000 次调用。 这意味着你的免费额度大约可以支持11,000 次地点搜索/详情查询。或 40,000 次地理编码/路径规划。 对于个人或小团队正常使用几乎不可能用完。但如果你在开发一个面向大量用户的应用就需要监控用量并在接近限额时考虑优化如上述缓存或设置用量限制。4. 错误处理的用户体验当API调用失败时如网络超时、配额耗尽不要直接向用户抛出一堆技术错误。你的AI助手或应用应该有一个友好的降级策略。例如“抱歉暂时无法获取实时地图信息。不过根据一般信息那个区域附近通常有不少咖啡馆……” 这比一个冰冷的“API Error 503”要好得多。7. 项目扩展与二次开发指南gmaps-mcp本身已经非常实用但开源项目的魅力在于你可以基于它进行定制和扩展。这里提供一些思路和入门指引。7.1 理解项目结构google-maps-mcp/ ├── pyproject.toml # 项目依赖和元数据 ├── run.py # HTTP服务器启动入口 └── src/google_maps_mcp/ ├── __init__.py ├── __main__.py # Stdio服务器启动入口 (python -m google_maps_mcp) ├── client.py # 核心封装Google Maps API客户端 ├── tools.py # 核心定义六个MCP工具 └── server.py # 核心创建FastMCP服务器集成Stdio/HTTPclient.py: 这里封装了与Google Maps API的直接HTTP通信。如果你需要修改请求参数、处理响应格式或添加日志这是主要修改点。tools.py: 这里定义了六个MCP工具的函数。每个函数都用mcp.tool()装饰器注册。如果你想添加一个新工具例如获取地点照片就在这里添加一个新函数。server.py: 这里创建了FastMCP服务器实例并注册了所有工具。同时它包含了将MCP服务器适配为HTTP服务的Starlette应用代码。7.2 添加一个新工具以“获取地点照片”为例假设你想添加一个get_place_photos工具用于获取地点的照片引用。研究Google Places API首先你需要查阅 Places API 文档 找到如何获取照片。通常Place Details响应中会包含一个photos数组里面有照片引用。你需要再用一个单独的Place Photos请求来获取可访问的URL。修改client.py在GoogleMapsClient类中添加一个新的方法例如get_place_photos(place_id, max_width400)该方法组合调用详情和照片API。修改tools.py添加一个新的工具函数。mcp.tool() async def get_place_photos(place_id: str, max_width: int 400) - dict: 获取指定地点的照片URL列表。 # 调用 client.py 中新增的方法 photos await mcp_server.client.get_place_photos(place_id, max_width) return { place_id: place_id, photos: photos # 返回一个包含照片URL和描述的列表 }在server.py中注册确保这个新工具函数被导入并添加到服务器实例中通常tools.py中的函数会自动注册取决于项目结构。测试重新启动服务器在Claude中尝试询问“能给我看看[某个地点]的照片吗”7.3 部署为Docker容器为了部署更便捷你可以为项目创建Dockerfile。# 使用官方Python镜像 FROM python:3.11-slim # 安装uv RUN pip install uv # 设置工作目录 WORKDIR /app # 复制项目文件 COPY pyproject.toml ./ COPY src ./src # 使用uv安装依赖 RUN uv sync --frozen # 复制环境变量文件生产环境中建议通过Docker secrets或运行时注入 COPY .env ./ # 暴露端口 EXPOSE 8000 # 启动命令 CMD [uv, run, python, run.py]然后构建并运行docker build -t gmaps-mcp-server . docker run -p 8000:8000 --env-file .env gmaps-mcp-server7.4 融入更大的AI应用生态gmaps-mcp的HTTP模式让它能轻松被其他系统集成。例如自动化工作流结合Zapier/Make或n8n当收到一封包含客户地址的邮件时自动调用geocode并存入CRM。数据分析定期调用search_nearby收集某个区域竞品门店的信息进行市场分析。多AI代理协作一个负责行程规划的Agent可以调用另一个部署了gmaps-mcp的Agent来获取地点和路线信息实现功能解耦。这个项目的设计充分体现了MCP协议的价值将复杂的能力封装成标准的、可互操作的接口。一旦你掌握了它就等于为你所有的AI应用打开了一扇通往真实世界地理空间数据的大门。从今天起让你的AI助手不再“纸上谈兵”而是真正能带你发现周边、规划路径的智能伙伴。