EmbedEarth is an open, programmable geographic layer for physical-world data. This MCP server gives AI agents structured tools for Search, Compute, Routing, Maps, and Stratum.

Install

npx -y @embedearth/mcp

Modes

Mode	Purpose
`auto`	Use verified local Stratum data first, then run the function in Cloud.
`offline`	Use only verified local data and make no network request.
`cloud`	Run the function in EmbedEarth Cloud. A key is optional, but unauthenticated use is heavily limited.

API key and limits

An API key is optional. Cloud Search, Compute, and Route requests are limited to 60 requests per minute without a key, or 2,000 requests per minute with a key. e2_stratum query without a key should be treated as one request per second. A key is also required for Street View image access. Create one at embed.earth and configure it as E2_API_KEY in the MCP host environment.

Search

e2_search returns matching physical-world records as a GeoJSON FeatureCollection. feature is a canonical key or numeric ID; use area, area_id, coordinates, or country_code and state_code to select the search scope.

Optional parameters

Parameter	Type	Purpose
`area`	`string \| string[]`	Search named areas. Mutually exclusive with `area_id`.
`area_id`	`string \| string[]`	Search exact area IDs. Mutually exclusive with `area`.
`country_code`	`string`	Select a country, for example `US`.
`state_code`	`string`	Select a state or province, for example `NY`.
`latitude`, `longitude`	`number`	Search around a coordinate. Provide both.
`mode`	`cloud \| offline \| auto`	Select the execution mode. Defaults to `auto`.
`limit`	`number`	Maximum number of returned features. Defaults to `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 }

Compute

e2_compute returns spatial analysis instead of raw records. feature is what is measured, area or area_id is the scope, and near or within names the related feature when needed.

Primitive	Purpose
`NEAREST`	Find the closest features.
`DISTANCE`	Measure distance between feature sets.
`WITHIN`	Select features inside a relation distance.
`COUNT`	Count related features.
`DENSITY`	Measure feature concentration.
`COVERAGE`	Measure reached area.
`GAPS`	Find unreached areas.
`CLUSTER`	Group nearby features.

{ "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" }

Routing

Routing builds directions and network-analysis responses from coordinates or indexed features. Use e2_route_to_feature for a coordinate-to-feature route and e2_route for direct routes, matrices, isochrones, map matching, locate, and height.

Set ROUTE_URL only when you want a custom compatible routing service.

Tool or operation	Purpose
`e2_route_to_feature`	Route from a coordinate to a matching feature, such as the closest restaurant.
`e2_route` with `route`	Build a route between one or more coordinates.
`e2_route` with `matrix`	Return travel costs between multiple sources and targets.
`e2_route` with `isochrone`	Calculate the area reachable within one or more time limits.
`e2_route` with `mapMatch`	Match a recorded coordinate trace to the road network.
`e2_route` with `locate`	Resolve a coordinate to the routable network.
`e2_route` with `height`	Return elevation data for one or more locations.

{ "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" } }

Maps

e2_map_sources prepares MapLibre-ready Planet and feature source descriptors. It returns map data metadata rather than rendering a map in the agent conversation.

Stratum

e2_stratum provides geographic lookup, published data discovery, verified caching, downloads, local queries, and namespaced uploads. Use it when an agent needs repeatable local data or must add user-owned GeoJSON, CSV, or Parquet features.

Operation	Purpose
`cacheList`, `cacheSet`, `cacheDelete`, `cacheClear`	Manage verified local data.
`featureList`, `featureSearch`, `featureInfo`	Look up built-in features.
`areaList`, `areaSearch`, `areaInfo`	Look up built-in areas.
`dataList`, `dataInfo`	Inspect published data.
`download`, `query`	Pull and query Cloud or local data.
`upload`	Add namespaced local data.

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

Geographical Features

Geographical features are the canonical physical-world types used across the MCP tools, including places, infrastructure, observations, and imagery-linked records. Browse them at Catalog Features.

Geographical Areas

Geographical areas are countries, states, cities, and other regions used to scope data. Browse names and stable IDs at Catalog Areas.

Street View Images

EmbedEarth ingests billions of Street View images and discovers new features or where imagery pairs with reported places. Street View is Cloud-only for now because of cost; an API key and an active subscription are required for unlimited use.