EmbedEarth (E2)

@embedearth/mcp

EmbedEarth（E2）是一个开放、可编程的物理世界地理引擎。此 MCP 服务为 AI Agent 提供用于 Search、Compute、Route、Map 和 Stratum 的结构化工具。

E2 是 Google Maps Platform 的开放替代方案，整合了通常分散在 Maps、Places、Routes、Geocoding、Autocomplete 和 Street View 中的功能，同时加入空间计算、开放地理数据和本地执行能力。

为什么选择 E2

传统地图 API 主要围绕地图、地点和路线构建。E2 让更广阔的物理世界变得可编程。

为 Agent 提供以下工具：

• Search 地点、基础设施、观测数据、自然要素、城市数据和其他真实世界要素。
• Compute 距离、邻近度、数量、密度、覆盖范围、空缺和其他空间关系。
• Map 底图、要素、路线和应用数据。
• Route 在坐标之间规划路线，或直接规划到真实世界要素的路线。
• Stratum 地理数据集，适用于本地、离线和云端工作流。
• 访问与地理位置关联的街景级影像和视觉观测数据。

对于使用 Google Maps Platform 集成的 Agent，E2 可以替代许多围绕 Maps、Places、Routes、Geocoding 和街景影像构建的常见工具工作流，同时让 Agent 直接访问更广泛的地理数据集并进行空间计算。

安装

npx -y @embedearth/mcp

模式

E2 可在本地或云端运行。每个区域的本地数据只需下载一次，之后的请求会重复使用，因此无需再次获取相同数据。

模式	用途
auto	优先使用可用的本地数据，否则使用云端。
offline	下载一次，之后在本地重复使用。
cloud	使用 API 密钥进行云端执行，不限使用次数。

API 密钥和限制

基本云端使用无需 API 密钥；配置密钥后即可解锁完整的云端访问权限。请在 embed.earth 创建密钥，并在 MCP 主机环境中将其配置为 E2_API_KEY；访问街景级影像也需要密钥。没有密钥时，云端 Search、Compute 和 Route 请求限制为每分钟 60 次，e2_stratum 的 query 应视为每秒一次请求。

Search

e2_search 可按要素、地点、区域或坐标搜索物理世界——通过一个工具搜索地点、基础设施、观测数据、自然要素、城市数据和其他地理数据集。它以 GeoJSON FeatureCollection 的形式返回匹配的物理世界记录。

feature 用于指定你想查找的内容；它可以是规范键或数字 ID。使用 area 指定命名区域，使用 area_id 指定确切区域，使用坐标进行点查询，或使用 country_code 和 state_code 选择更广泛的地理范围。

可选参数

参数	类型	用途
area	string | string[]	搜索命名区域。不能与 area_id 同时使用。
area_id	string | string[]	搜索确切的区域 ID。不能与 area 同时使用。
country_code	string	选择国家/地区，例如 US。
state_code	string	选择州或省，例如 NY。
latitude、longitude	number	搜索坐标周边。两者都必须提供。
mode	cloud | offline | auto	选择执行模式。默认为 auto。
limit	number	返回要素的最大数量。默认为 1000。

{ "feature": "restaurant", "area": "New York", "mode": "auto", "limit": 25 }

{ "feature": "restaurant", "area_id": "4915", "mode": "cloud", "limit": 25 }

{ "feature": "restaurant", "latitude": 40.7128, "longitude": -74.006, "mode": "cloud", "limit": 25 }

{ "feature": "restaurant", "country_code": "US", "state_code": "NY", "mode": "cloud", "limit": 25 }

计算

e2_compute 直接针对地理要素运行空间分析——查找最近对象、测量距离、统计要素数量、计算密度和覆盖范围、检测空白区域，或对附近对象进行聚类；无需单独的 GIS 技术栈，即可将地理数据转化为答案。

feature 定义要测量的对象，而 area 或 area_id 定义地理范围。near 等关系参数用于关联不同的要素集。

原语	用途
NEAREST	查找最近的要素。
DISTANCE	测量要素集之间的距离。
WITHIN	选择位于关系距离范围内的要素。
COUNT	统计相关要素。
DENSITY	测量要素密度。
COVERAGE	测量覆盖区域。
GAPS	查找未覆盖区域。
CLUSTER	将附近要素分组。

{ "primitive": "COUNT", "feature": ["restaurant"], "area_id": "4915", "near": "park", "distanceMeters": 500, "mode": "cloud" }

{ "primitive": "DENSITY", "feature": ["restaurant"], "area": "New York", "near": "park", "distanceMeters": 500, "mode": "auto" }

路线规划

计算在现实世界中的移动路线。根据坐标或 E2 要素构建路线、行程时间矩阵、等时圈、地图匹配和高程查询，以及考虑路网的搜索，让 Agent 能导航到具体地点，而不只是固定坐标。使用 e2_route_to_feature 规划从坐标到要素的路线，使用 e2_route 执行直接路线规划、矩阵计算、等时圈计算、地图匹配、定位和高度查询。

仅在使用自有的兼容路线规划服务时设置 ROUTE_URL。

工具或操作	用途
e2_route_to_feature	从坐标导航到匹配的要素，例如最近的餐厅。
带有 route 的 e2_route	构建一个或多个坐标之间的路线。
带有 matrix 的 e2_route	返回多个起点和终点之间的行程成本。
带有 isochrone 的 e2_route	计算一个或多个时间限制内可到达的区域。
带有 mapMatch 的 e2_route	将记录的坐标轨迹匹配到路网。
带有 locate 的 e2_route	将坐标定位到可通行路网。
带有 height 的 e2_route	返回一个或多个位置的高程数据。

{ "feature": "restaurant", "from": [40.7128, -74.006], "mode": "walking" }

{ "operation": "matrix", "body": { "sources": [{ "lat": 40.7128, "lon": -74.006 }], "targets": [{ "lat": 40.7306, "lon": -73.9352 }], "mode": "driving" } }

地图

e2_map_sources 将 E2 数据渲染为兼容 MapLibre 的地图数据源——全球 Planet 底图和 PMTiles 要素图层。它返回地图数据元数据，而不是在 Agent 对话中渲染地图，因此样式设置和交互由客户端应用程序处理。

Stratum

e2_stratum 是 E2 面向地理数据集的可移植数据层。你可以发现、下载、缓存、查询和上传地理数据，用于本地或云端工作流，无需维护传统空间数据库。它支持 GeoJSON、CSV、Parquet 和 SQLite，可将数据集下载一次，随后在不同应用程序和地区中重复使用。

操作	用途
cacheList、cacheSet、cacheDelete、cacheClear	管理已验证的本地数据。
featureList、featureSearch、featureInfo	查找内置要素。
areaList、areaSearch、areaInfo	查找内置区域。
dataList、dataInfo	检查已发布的数据。
download、query	获取并查询云端或本地数据。
upload	添加带命名空间的本地数据。

{ "operation": "upload", "path": "./stores.geojson", "database": "./stores.db", "feature": "stores", "namespace": "my-app" }

地理目录

E2 将现实世界组织为要素和区域。

要素描述存在的事物——地点、基础设施、观测记录、自然要素、关联影像的记录，以及其他现实世界中的对象。

区域描述地点范围——国家、州、城市和其他具有稳定 ID 的地理区域。

浏览要素和区域目录，发现 Search、Compute、Route 和 Stratum 中可用的输入：要素目录 · 区域目录。

街景影像

EmbedEarth 处理数十亿张街景图像，将视觉观察结果与地理要素和地点相关联。影像为位置增添视觉背景信息，并可呈现传统地点数据库中可能未收录的现实世界要素。

街景影像目前基于云端，需要 API 密钥和有效套餐。

其他接口

SDK 包 · CLI 包 · 完整 MCP 文档