geeViz.mcp.server¶

geeViz MCP Server – execution and introspection tools for Earth Engine via geeViz.

Unlike static doc snippets, this server executes code, inspects live GEE assets, and dynamically queries API signatures. 12 tools.

Functions

`env_info`([action, session_id])	Get environment information: versions, REPL namespace, or project details.
`export_image`(destination, image_var[, ...])	Export an ee.Image to a GEE asset, Google Drive, or Cloud Storage.
`inspect_asset`(asset_id[, start_date, ...])	Get detailed metadata for any GEE asset (Image, ImageCollection, FeatureCollection, etc.).
`main`()	CLI entry point — start the geeViz MCP server on stdio transport.
`manage_asset`(action[, asset_id, dest_id, ...])	Manage GEE assets: delete, copy, move, create folders, update permissions.
`map_control`([action, open_browser, ...])	Control the geeView interactive map.
`run_code`(code[, timeout, reset, ...])	Execute Python/GEE code in a persistent REPL namespace (like Jupyter).
`save_session`([filename, format, sliced, ...])	Save the accumulated run_code history to a .py script or .ipynb notebook.
`search_codebase`([query, name, module, ...])	Search geeViz — plus any module in the REPL namespace (ee, pandas, numpy, etc.).
`search_datasets`(query[, source, max_results])	Search the GEE dataset catalog PLUS BigQuery public data by keyword.
`view_output`(filename[, session_id])	View a generated output file (PNG, GIF, JPEG) as an inline image.

async geeViz.mcp.server.run_code(code: str, timeout: int = 120, reset: bool = False, stream_stdout: bool = False, session_id: str = None, ctx: Context = None) → str[source]¶

Execute Python/GEE code in a persistent REPL namespace (like Jupyter).

The namespace persists across calls – variables set in one call are available in the next. Pre-populated with: ee, Map (gv.Map), gv (geeViz.geeView), gil (geeViz.getImagesLib), sal (geeViz.getSummaryAreasLib), tl (geeViz.outputLib.thumbs), rl (geeViz.outputLib.reports), save_file.

Sandbox mode: When the server is run with --sandbox or over HTTP to a non-localhost address, open(), os, sys, eval, etc. are blocked. For local/stdio use (the default), sandbox is OFF and full Python access is available. Use save_file(filename, content) to write files to the generated_outputs/ directory regardless of sandbox mode.

While executing, progress heartbeats are sent every ~10 seconds to keep the MCP client connection alive and inform the agent that the tool is still running.

Parameters:

code – Python code to execute.
timeout – Max seconds to wait (default 120). On Windows a hung getInfo() cannot be force-killed; the thread continues in background.
reset – If True, clear the namespace and re-initialize before executing.
stream_stdout – If True, print output is available in real-time via the /stdout polling endpoint. Default False.
session_id – Session identifier for namespace isolation. Default None (shared default session).
ctx – MCP Context (auto-injected by FastMCP). Used for progress reporting.

Returns:

success (bool), stdout, stderr, result, error.

Return type:

JSON with keys

geeViz.mcp.server.inspect_asset(asset_id: str, start_date: str = '', end_date: str = '', region_var: str = '', session_id: str = None) → str[source]¶

Get detailed metadata for any GEE asset (Image, ImageCollection, FeatureCollection, etc.).

Returns band names/types, CRS, scale, date range, size, columns, and properties. Uses ee.data.getInfo for fast catalog metadata, then fetches live details with a 10-second timeout per query to avoid hangs on large collections. Also handles BigQuery-backed FeatureCollections — when the standard catalog lookup returns “not found” and the id looks BQ-shaped (project.dataset.table), retries via ee.FeatureCollection.loadBigQueryTable so tables like bigquery-public-data.overture_maps.place describe cleanly.

Parameters:

asset_id – Full Earth Engine asset ID (e.g. "COPERNICUS/S2_SR_HARMONIZED") OR a BigQuery table path in the form project.dataset.table (e.g. "bigquery-public-data.overture_maps.place"). EE catalog is tried first; BQ is the fallback.
start_date – Optional start date filter for ImageCollections (YYYY-MM-DD).
end_date – Optional end date filter for ImageCollections (YYYY-MM-DD).
region_var – Optional name of an ee.Geometry or ee.FeatureCollection variable in the REPL namespace for spatial filtering (ImageCollections only).

Returns:

JSON with asset metadata. For BQ-backed hits, source=bigquery is set so the caller knows to use ee.FeatureCollection.loadBigQueryTable (not ee.FeatureCollection) when constructing the FC.

geeViz.mcp.server.search_codebase(query: str = '', name: str = '', module: str = '', session_id: str = None) → str[source]¶

Search geeViz — plus any module in the REPL namespace (ee, pandas, numpy, etc.).

A unified introspection tool. Look up functions, classes, dicts, constants, viz params, band mappings, palettes, method signatures, example scripts — anything reachable by name.

Modules it searches

Every geeViz module (getImagesLib, getSummaryAreasLib, geeView, geePalettes, edwLib, googleMapsLib when available, outputLib.charts / .thumbs / .reports, etc.) — indexed via AST at startup, so no imports fire until you actually request a runtime value.
Example scripts under geeViz/examples/ — module="examples" lists them, name="<script_name>" returns source.
Any module already loaded in the REPL namespace — that includes Earth Engine (ee), pandas (pd / pandas), numpy (np / numpy), and anything else prior run_code blocks imported. Pass module="ee" / module="pd" / etc. to browse.

Parameters:

query – Search term (case-insensitive). Matches against names and first-line docstrings across every indexed module.
name – Exact name to look up. Accepts bare names ("vizParamsFalse", "simpleMask", "DataFrame.to_markdown") or dotted paths ("getImagesLib.vizParamsFalse", "mapper.addLayer", "ee.Image.reduceRegion", "pd.DataFrame"). Returns full details — signature and docstring for functions; keys / values for dicts; value for constants.
module – Module to search or list. Accepts short geeViz names ("getImagesLib", "charts", "thumbs"), full paths ("geeViz.outputLib.charts"), legacy aliases ("chartingLib"), or any REPL-loaded module ("ee", "pandas" / "pd", "numpy" / "np").

Returns:

No args: list of all discovered modules
module only: all public members (functions, classes, variables)
query only: search results across all modules
name only: detailed description of the named object
name + module: direct lookup within a specific module

Return type:

JSON with results. Shape depends on the query

geeViz.mcp.server.map_control(action: str = 'view', open_browser: bool = True, filename: str = 'map.html', session_id: str = None)[source]¶

Control the geeView interactive map.

action="view" writes the per-session runGeeViz.js to disk and opens geeView/index.html. In plain Python this is a file:/// URL; in notebooks it uses an in-process threaded HTTP server (http://localhost:<port>/...) for iframe display. The access token is passed via URL query string.

Supported action values:

"view" (default) — validates all layers first (runs test_layers internally). If any layer fails, returns the errors without opening the map. If all pass, opens the map and returns the URL.
"layers" — list current layers with visibility and viz params.
"layer_names" — quick list of just layer names (lightweight).
"clear" — remove all layers and commands.
"test_layers" — fast validation, calls getMapId() on all layers in parallel. Catches bad bands, invalid viz, computation errors. No browser required. Returns pass/fail per layer.
"preview" — quick visual check. Fetches a small grid of EE map tiles for each layer around the current center/zoom and returns them as inline images (one per layer). No browser required. Use to visually verify layers have data in the right area. Returns {layer_name: PNG image} plus center and zoom. Optional: "preview,zoom=10,grid=2" to override zoom or grid.
"export" — validates all layers first (like "view"), then writes a self-contained geeView HTML to generated_outputs/{filename}. If any layer fails, returns errors without exporting. The HTML uses absolute asset paths under /geeView/static and a __GEEVIZ_TOKEN__ placeholder for the access token. Suitable for chat UIs that serve the HTML themselves and inject a fresh token on load. Use this for chat-embedded maps that should survive session reloads.
"export_layers_json" — bundle every currently-added layer into a JSON file under generated_outputs/{filename}. Use when the agent is building a CUSTOM HTML dashboard (Leaflet, MapLibre, etc.) and needs the EE layers to be re-mintable. The returned refresh_url is an endpoint the agent embeds in its HTML; fetching it returns fresh tile URLs for every layer so dashboards survive after EE map IDs expire. Handles all the same input types as addLayer (Image, ImageCollection, Geometry, Feature, FeatureCollection) plus tile-URL layers added via Map.addTileLayer.

Parameters:

action – One of the values listed above.
open_browser – For action="view", whether to open in browser (default True).
filename – For action="export", the output filename (saved under generated_outputs/). Defaults to map.html.
session_id – Session identifier for namespace isolation.

Returns:

JSON with action-specific results.

geeViz.mcp.server.save_session(filename: str = '', format: str = 'py', sliced: bool = True, session_id: str = None) → str[source]¶

Save the accumulated run_code history to a .py script or .ipynb notebook.

Parameters:

filename – Optional custom filename (saved in geeViz/mcp/generated_scripts/). If omitted, uses a timestamped default. The correct extension is added automatically based on format.
format – Output format – “py” (default) for a standalone Python script, “ipynb” for a Jupyter notebook.
sliced – When True (default), run backward program slicing anchored on the last successful block and emit ONLY the surviving blocks — exploratory dead code and superseded assignments are dropped. When False, emit every successful block verbatim (legacy behavior; useful when the slicer’s judgment is wrong for a specific session). See _slice_history for the rules.

Returns:

JSON with the file path, block-retention counts, and status.

geeViz.mcp.server.env_info(action: str = 'version', session_id: str = None) → str[source]¶

Get environment information: versions, REPL namespace, or project details.

Parameters:: action – What to return: - “version” (default): geeViz, EE, and Python versions. - “namespace”: User-defined variables in the REPL (no getInfo calls). - “project”: Current EE project ID and root assets.
Returns:: JSON with action-specific results.

geeViz.mcp.server.view_output(filename: str, session_id: str = None)[source]¶

View a generated output file (PNG, GIF, JPEG) as an inline image.

Use this to visually inspect charts, thumbnails, previews, or any image file in the generated_outputs directory. The image is returned directly so the LLM can see it.

For map previews, first call map_control(action=”preview”) to generate preview PNGs, then call view_output(“preview_Layer_Name.png”) to see them.

Parameters:

filename – Name of the file in generated_outputs/ (e.g. “chart.png”, “preview_Elevation.png”). Just the filename, no directory.
session_id – Session identifier for namespace isolation.

Returns:

The image content (displayed inline by the MCP client), or an error string.

geeViz.mcp.server.export_image(destination: str, image_var: str, region_var: str = '', scale: int = 30, crs: str = 'EPSG:4326', overwrite: bool = False, asset_id: str = '', pyramiding_policy: str = 'mean', output_name: str = '', drive_folder: str = '', bucket: str = '', output_no_data: int = -32768, file_format: str = 'GeoTIFF', session_id: str = None) → str[source]¶

Export an ee.Image to a GEE asset, Google Drive, or Cloud Storage.

Parameters:

destination – Where to export – “asset”, “drive”, or “cloud”.
image_var – Name of the ee.Image variable in the REPL namespace.
region_var – Name of an ee.Geometry or ee.FeatureCollection variable for the export region. Required for drive/cloud exports; optional for asset exports (uses image footprint if omitted).
scale – Output resolution in meters (default 30).
crs – Coordinate reference system (default “EPSG:4326”).
overwrite – If True, overwrite existing asset/file (default False).
Asset-specific – asset_id: Full destination asset ID (required for destination=”asset”). pyramiding_policy: “mean” (default), “mode”, “min”, “max”, “median”, “sample”.
Drive-specific – output_name: Output filename without extension (required for drive/cloud). drive_folder: Google Drive folder name (required for destination=”drive”).
Storage-specific (Cloud) – output_name: Output filename without extension (required for drive/cloud). bucket: GCS bucket name (required for destination=”cloud”). output_no_data: NoData value (default -32768). file_format: “GeoTIFF” (default) or “TFRecord”.

Returns:

JSON with export status or an error.

geeViz.mcp.server.search_datasets(query: str, source: str = 'all', max_results: int = 50) → str[source]¶

Search the GEE dataset catalog PLUS BigQuery public data by keyword.

Searches three catalogs, all cached with 30-day stale-while-revalidate:

official — Earth Engine STAC catalog (~500+ datasets).
community — awesome-gee-community-datasets (~200+ datasets).
bigquery — every dataset AND table under bigquery-public-data (~357 datasets, ~3000 tables). Table-level indexing means a query like “overture places” resolves directly to bigquery-public-data.overture_maps.place — no need to enumerate tables yourself afterwards. Results have source=bigquery, plus kind set to "dataset" or "table". For a BQ table row, construct the FeatureCollection with ee.FeatureCollection.loadBigQueryTable(id) — NOT ee.FeatureCollection(id) — because the id is a BQ path, not an EE asset path. inspect_asset on a BQ id auto-falls back through the same helper.

Uses word-level matching against title, tags, id, and provider fields with relevance scoring.

Parameters:

query – Search terms (e.g. “landsat surface reflectance”, “DEM”, “sentinel fire”, “overture places”). Case-insensitive.
source – Which catalog to search: “official”, “community”, “bigquery”, or “all” (default — spans all three).
max_results – Maximum number of results to return (default 50).

Returns:

JSON list of matching datasets with id, title, type, provider, tags, source, and additional metadata.

geeViz.mcp.server.manage_asset(action: str, asset_id: str = '', dest_id: str = '', overwrite: bool = False, folder_type: str = 'Folder', all_users_can_read: bool = False, readers: str = '', writers: str = '', session_id: str = None) → str[source]¶

Manage GEE assets: delete, copy, move, create folders, update permissions.

Parameters:

action – Operation to perform: - “delete”: Delete a single asset. - “copy”: Copy asset_id to dest_id. - “move”: Copy asset_id to dest_id, then delete source. - “create”: Create a folder or ImageCollection at asset_id. - “update_acl”: Update permissions on asset_id.
asset_id – Full asset path. Required for all actions. For “create”, this is the folder path to create.
dest_id – Destination path (required for “copy” and “move”).
overwrite – If True, overwrite existing destination (default False).
folder_type – For action=”create” – “Folder” (default) or “ImageCollection”.
all_users_can_read – For action=”update_acl” – make publicly readable.
readers – For action=”update_acl” – comma-separated reader emails.
writers – For action=”update_acl” – comma-separated writer emails.

Returns:

JSON confirmation or error.

geeViz.mcp.server.main() → None[source]¶

CLI entry point — start the geeViz MCP server on stdio transport.

Reads config from the environment (EE_PROXY_URL, GEE_PROJECT, GEE_SERVICE_ACCOUNT_B64, MCP_SANDBOX, MCP_STREAM_DIR), spawns a background prewarm thread that eagerly initializes EE + imports the heavy geeViz modules, then blocks in app.run() speaking JSON-RPC over stdin/stdout for the MCP client (Claude Desktop, ADK, etc.).

Invoked as python -m geeViz.mcp or by an MCP client configured with command: python -m geeViz.mcp.