MCP Server¶
geeViz includes a Model Context Protocol (MCP) server that lets AI coding IDEs (Cursor, VS Code + GitHub Copilot, Claude Code, Google Antigravity, Zed, JetBrains AI Assistant, Continue, Windsurf), terminal agents (OpenAI Codex CLI, Gemini CLI, Warp), and desktop chat apps (Claude Desktop, ChatGPT Desktop) interact with geeViz and Google Earth Engine directly.
Why MCP?¶
An AI coding agent already has powerful general-purpose tools — it can search the web, read local files, grep source code, and write scripts. So why add an MCP server on top of that?
The core problem is that Earth Engine is a live, authenticated cloud platform. General-purpose tools can read about GEE but cannot interact with it. The MCP server bridges that gap by giving the agent 12 purpose-built tools that execute against your authenticated GEE session and the actual geeViz codebase. The table below compares what each approach can do for common GEE tasks:
Task |
Vanilla coding agent (web search, grep, file read) |
geeViz MCP server |
|---|---|---|
Look up a geeViz function signature |
Grep source files or search the web — may find outdated docs, wrong version, or miss internal helpers |
|
Find which module has a function |
|
|
Check what bands a dataset has |
Search the GEE data catalog website, parse HTML, hope the page is current |
|
Get image count and date range for a filtered collection |
Write and run a script with multiple |
|
Search for GEE datasets by keyword |
Web search, browse the GEE catalog, read blog posts |
|
Get detailed dataset metadata (bands, classes, scale/offset) |
Find and parse the STAC JSON page for the dataset |
|
Test a code snippet |
Write to a file, run it in a terminal, read stdout/stderr |
|
Build up an analysis incrementally |
Each script run starts fresh; agent must manage state manually |
|
See what variables exist after several code steps |
Re-read the script, mentally track assignments |
|
Visualize results on a map |
Write code to call |
|
Get a visual preview of an image |
Write a |
|
Sample pixel values or chart zonal statistics |
Write |
|
Geocode a place name to a GEE geometry |
Call a geocoding API, manually construct |
|
Export an image to an asset |
Write export code, look up |
|
Export to Drive or Cloud Storage |
Write export boilerplate, remember required parameters |
|
Check task status or cancel tasks |
Write |
|
Manage assets (copy, move, delete, permissions) |
Write 5-10 lines of |
|
Read a geeViz example script |
|
|
Save the session as a reusable script |
Manually copy code blocks from the conversation |
|
In short: a vanilla agent can read about GEE; the MCP lets it use GEE. Every tool returns structured data rather than text to parse, handles authentication and error cases, and exposes domain-specific parameters (reducers, CRS, pyramiding policies, STAC metadata) that a general-purpose search would never surface reliably.
What is MCP?¶
MCP (Model Context Protocol) is an open standard that connects AI tools to external capabilities via tools — callable functions the AI can invoke during a conversation. The geeViz MCP server exposes 12 tools that the AI discovers automatically when it connects. No special prompting or configuration beyond the initial setup is required.
Quick Start¶
This section walks through the complete setup. It takes about two minutes.
Step 1: Install geeViz¶
The mcp SDK is included as a dependency of geeViz, so a single install is all you need:
$ pip install geeViz
You can confirm the server is available:
$ python -m geeViz.mcp.server --help
Step 2: Make sure Earth Engine auth works¶
The MCP server initializes Earth Engine on its first tool call. If you haven’t authenticated recently, do it now so the server doesn’t hang waiting for a browser prompt:
$ python -c "import ee; ee.Authenticate(); ee.Initialize(project='your-project-id'); print(ee.Number(1).getInfo())"
If that prints 1, you’re good.
Step 3: Add the config for your editor¶
Pick your editor and create the config file shown below. Each one tells the editor how to start the geeViz MCP server as a subprocess.
Cursor
Create .cursor/mcp.json in your project root (or add via Cursor Settings → MCP):
{
"mcpServers": {
"geeviz": {
"command": "python",
"args": ["-m", "geeViz.mcp.server"]
}
}
}
VS Code / GitHub Copilot
Create .vscode/mcp.json in your project root:
{
"servers": {
"geeviz": {
"command": "python",
"args": ["-m", "geeViz.mcp.server"],
"cwd": "${workspaceFolder}"
}
}
}
For best results, also create .github/copilot-instructions.md to tell Copilot how to use the tools (see Agent Instructions File below).
Claude Code
Create .claude/mcp.json in your project root:
{
"mcpServers": {
"geeviz": {
"command": "python",
"args": ["-m", "geeViz.mcp.server"]
}
}
}
Google Antigravity
Antigravity is Google’s agent-first AI IDE. Add the server via Settings → MCP Servers, or create .antigravity/mcp.json in the project root:
{
"mcpServers": {
"geeviz": {
"command": "python",
"args": ["-m", "geeViz.mcp.server"]
}
}
}
OpenAI Codex CLI
Codex CLI is OpenAI’s terminal-based coding agent with native MCP support. Add via codex mcp add:
$ codex mcp add geeviz python -- -m geeViz.mcp.server
Or edit ~/.codex/config.toml:
[mcp_servers.geeviz]
command = "python"
args = ["-m", "geeViz.mcp.server"]
Zed
Zed supports MCP servers via the Assistant panel. Add in settings.json:
{
"context_servers": {
"geeviz": {
"command": {
"path": "python",
"args": ["-m", "geeViz.mcp.server"]
}
}
}
}
Warp
Warp terminal supports MCP servers for its Agent Mode. Add via Settings → AI → Manage MCP Servers, then paste:
{
"geeviz": {
"command": "python",
"args": ["-m", "geeViz.mcp.server"]
}
}
JetBrains AI Assistant (IntelliJ, PyCharm, WebStorm, etc.)
JetBrains AI Assistant supports MCP via the AI Assistant settings. Add mcp.json in your project:
{
"mcpServers": {
"geeviz": {
"command": "python",
"args": ["-m", "geeViz.mcp.server"]
}
}
}
Continue.dev
Continue (open-source IDE assistant) adds MCP servers via config.yaml:
mcpServers:
- name: geeviz
command: python
args: ["-m", "geeViz.mcp.server"]
Windsurf / Other MCP Clients
Any MCP client that supports stdio transport can connect. The server command is always:
$ python -m geeViz.mcp.server
Important
geeViz must be importable from the working directory. If you installed via pip install geeViz, any directory works. If you are using a development checkout, set the working directory to the parent of the geeViz package folder.
Step 4: Verify it works¶
Open your AI assistant’s chat and ask it something that requires the MCP tools:
"What bands does COPERNICUS/S2_SR_HARMONIZED have?"
If the MCP server is connected, the AI will call inspect_asset("COPERNICUS/S2_SR_HARMONIZED") and return the real band list from Earth Engine. If it just guesses from memory, the server isn’t connected — check your config file path and restart the editor.
You can also try:
"List the geeViz example scripts that involve LANDTRENDR"
The AI should call search_geeviz(module="examples", query="LANDTRENDR") and return actual filenames from your geeViz installation.
Agent Instructions File¶
MCP gives the AI tools, but it doesn’t always know when to use them. The geeViz MCP server solves this by automatically serving agent instructions to every connected client via the MCP instructions protocol field. When your AI assistant connects, it receives rules, workflow patterns, and the full list of all 12 tools — no manual setup required.
The instructions are loaded from geeViz/mcp/agent-instructions.md, which also ships with the package for reference. If your editor supports additional instructions files, you can copy the contents there for extra reinforcement:
Editor |
Instructions file |
|---|---|
VS Code / GitHub Copilot |
|
Cursor |
|
Claude Code |
|
Windsurf |
|
Tip
MCP tools vs instructions files — what’s the difference?
An instructions file is static text injected into the AI’s context. It tells the AI what to do, but gives it no new capabilities. The AI still cannot verify its code, check an asset’s bands, or test whether something runs.
MCP tools are callable functions the AI invokes during its response. It can stop mid-thought, call search_geeviz, read the real signature, and write correct code.
Use both. The instructions file tells the AI when to reach for the tools. The MCP server gives it the tools to reach for. Without instructions, the AI has tools but may not think to use them. Without MCP, the instructions are just more docs for the AI to hallucinate from.
HTTP Transport (Advanced)¶
For non-stdio clients, the server supports HTTP transport via environment variables. See also Tools Reference in the “Using Without an IDE” section for more details.
$ set MCP_TRANSPORT=streamable-http
$ set MCP_HOST=127.0.0.1
$ set MCP_PORT=8000
$ python -m geeViz.mcp.server
Using Without an IDE¶
If you can’t use the MCP server through a coding IDE, there are several other options for local use.
Desktop AI Apps¶
These are the lowest-friction options — install the app, add the config, and start chatting.
Claude Desktop
Add to your Claude Desktop config file (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"geeViz": {
"command": "python",
"args": ["-m", "geeViz.mcp.server"]
}
}
}
Restart Claude Desktop. The 12 geeViz tools will appear automatically.
ChatGPT Desktop
ChatGPT Desktop also supports MCP servers. Add the same server command (python -m geeViz.mcp.server) in ChatGPT’s MCP configuration.
Terminal¶
Gemini CLI
Google’s Gemini CLI supports MCP servers directly:
$ gemini --mcp-server "python -m geeViz.mcp.server"
Or add to your .gemini/settings.json:
{
"mcpServers": {
"geeViz": {
"command": "python",
"args": ["-m", "geeViz.mcp.server"]
}
}
}
Claude Code (CLI)
Claude Code is a terminal-based AI agent (not an IDE). Add the server to your project:
$ claude mcp add geeViz python -- -m geeViz.mcp.server
Or create .mcp.json in your project root:
{
"mcpServers": {
"geeViz": {
"command": "python",
"args": ["-m", "geeViz.mcp.server"]
}
}
}
Python Script or Jupyter Notebook¶
You can connect to the MCP server programmatically using the mcp Python client library and pipe tool calls through any LLM API (Gemini, Claude, OpenAI). This approach gives you full control over prompts, tool routing, and output handling — ideal for batch testing, automated workflows, or custom integrations.
The geeViz package includes two examples:
geeViz/mcp/mcp_with_gemini_tutorial.ipynb— Jupyter notebook tutorial for using the MCP server with Gemini
Both use python-dotenv to load a GOOGLE_API_KEY from a .env file. The core pattern:
import subprocess
from mcp.client.session import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client
server_params = StdioServerParameters(
command="python",
args=["-m", "geeViz.mcp.server"],
)
# errlog=subprocess.DEVNULL needed in Jupyter on Windows
async with stdio_client(server_params, errlog=subprocess.DEVNULL) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
tools = await session.list_tools() # discover all 12 tools
result = await session.call_tool( # call any tool
name="env_info", arguments={"action": "version"}
)
This connects to the MCP server as a subprocess and exposes the same 12 tools that IDE integrations use. You can then feed tool schemas and results to any LLM via its API.
HTTP Server¶
Run the MCP server with HTTP transport for access from any HTTP-capable MCP client:
$ set MCP_TRANSPORT=streamable-http
$ set MCP_PORT=8080
$ python -m geeViz.mcp.server
Any MCP client that supports streamable-http transport can connect to http://localhost:8080/mcp. This is also the path to Cloud Run deployment for remote access.
Choosing the Right Option¶
Option |
Setup effort |
Best for |
Notes |
|---|---|---|---|
Coding IDE (Cursor, VS Code, Zed, Antigravity, Continue, JetBrains) |
Low |
Daily development |
Tightest integration — tools appear inline while coding. The agent can lookup signatures with |
Terminal agents (Claude Code, Codex CLI, Gemini CLI, Warp) |
Low |
Terminal users, one-off analyses |
Full agent capabilities from the command line; excellent for scripting workflows outside an IDE |
Desktop chat apps (Claude Desktop, ChatGPT Desktop) |
Low |
Chat-style exploration |
No coding required, conversational interface. Best for “show me…” / “generate a report on…” prompts |
Python script / notebook |
Medium |
Batch testing, custom workflows |
Full control over prompts and output handling; feed tool schemas to any LLM API |
HTTP server |
Medium |
Remote/shared access, Cloud Run |
Any HTTP MCP client can connect; path to hosted deployment |
Coding Agent vs. General Agent Workflows¶
The MCP server serves two distinct usage patterns. Both work — the setup and expected interactions differ.
Coding agent (Cursor, VS Code + Copilot, Claude Code, Codex CLI, Antigravity, Zed, JetBrains, Continue, Warp)
You’re editing a .py script and want the agent to fill in real, executable geeViz code. The instructions file (.github/copilot-instructions.md, CLAUDE.md, etc.) primes the agent; the MCP tools verify what it writes.
Typical loop:
Ask: “Add LCMS change detection for the Uinta-Wasatch NF to this notebook.”
Agent calls
search_geeviz(query="LCMS")to find the right module + example.Agent calls
search_geeviz(name="getLCMSStack")to read the real signature.Agent writes the code into your file.
Agent calls
run_codeto execute the block against your authenticated GEE session.Agent calls
inspect_asseton any dataset it uses to verify bands / date range before charting.Agent calls
map_control(action="test_layers")as a quality gate beforeview.
Value: the agent’s output is grounded. It didn’t hallucinate a signature, guess a band name, or write code that fails at runtime — it verified each step.
General / chat agent (Claude Desktop, ChatGPT Desktop, Gemini CLI, hosted assistants)
You’re in a conversation and want output — a map, a chart, a report — not a codebase. There’s no .py file to save into; the agent uses the MCP server as its scratch environment.
Typical loop:
Ask: “Show me a report on burn severity in the Cameron Peak fire area.”
Agent calls
geeviz_search_places("Cameron Peak fire, Colorado")for coordinates.Agent calls
search_geeviz(query="MTBS")to find the burn-severity library.Agent calls
run_codeto buildrl.Report(...)with several sections (imagery before/after, severity classification, chart of area burned).report.generate()runs in strict mode — if any section errors, the agent sees the exception and retries; otherwise it savesreport.htmland returns the file.Agent calls
view_output("report.html")to open the finished report in the user’s browser.
Value: the agent produces an artifact. The user gets a report / map / chart they can share, without writing or maintaining Python.
Both patterns use the same 12 tools — no separate configuration. What differs is how the agent instructions guide the conversation. The instructions file ships with both a coding-first mode and a chat-first mode; the MCP server serves them to any client that reads the instructions protocol field.
Tools Reference¶
The server exposes 12 tools. Charting, thumbnails, reports, EDW queries, and geocoding are reached through run_code using pre-loaded aliases (cl, tl, rl, edwLib, gm) — one execution primitive plus a rich REPL namespace beats a proliferation of narrow wrappers.
Category |
Tools |
|---|---|
Code execution |
|
API introspection |
|
Dataset discovery |
|
Asset inspection |
|
Map control |
|
Exports & asset management |
|
Google Maps |
|
Environment |
|
For each tool’s exact parameters and docstrings, see the auto-generated API reference: geeViz.mcp.server. For everything reached through run_code (charts, thumbnails, reports, EDW, geocoding), the same APIs work standalone — see geeViz.outputLib, geeViz.getSummaryAreasLib, geeViz.edwLib, and geeViz.googleMapsLib.
How It Works¶
Architecture¶
The MCP server uses lazy initialization — it does not import geeViz or initialize Earth Engine until the first tool call that needs it. This keeps startup fast and avoids authentication prompts when running --help.
A persistent namespace (a Python dict) acts as shared state across run_code calls:
run_code("x = 42") → _namespace["x"] = 42
run_code("print(x)") → prints 42 (x is still there)
run_code(..., reset=True) → _namespace cleared, ee/Map/gv/gil/sal re-added
The Map object in this namespace is the same singleton (geeViz.geeView.Map) that map_control (with action="view"|"export"|"layers"|"layer_names"|"clear"|"test_layers"|"test_view") operates on. No object passing is needed. Both view and export automatically validate all layers before proceeding.
Script Saving¶
Every successful run_code call appends the code to an internal history and writes it to a .py file in geeViz/mcp/generated_scripts/. The file includes:
Standard geeViz imports (
gv,gil,ee,Map)Each code block labeled with its call number
Full standalone script — copy it out and run it directly
Timeouts¶
run_code uses a background thread with a configurable timeout (default 120 seconds). On Windows, a hung getInfo() call cannot be forcibly terminated — the thread continues in background. This is a known platform limitation.
Example Workflow¶
Here is what a typical AI-assisted session looks like with the MCP server. The AI calls tools behind the scenes:
User: "Do LANDTRENDR change detection near Bozeman and show me the results"
AI calls: search_geeviz(query="LANDTRENDR") # find relevant modules + examples
AI calls: search_geeviz(module="examples",
name="LANDTRENDRWrapper") # read the reference script
AI calls: search_geeviz(name="simpleLANDTRENDR") # confirm the exact signature
AI calls: run_code("""
import geeViz.changeDetectionLib as cdl
studyArea = ee.Geometry.Point([-111.04, 45.68]).buffer(20000)
...
""")
AI calls: run_code("Map.centerObject(studyArea)")
AI calls: map_control(action="test_layers") # quality gate before view
AI calls: map_control(action="view")
AI responds: "Here's your LANDTRENDR analysis. The map has been rendered
and opened in the browser, and the script has been saved to
geeViz/mcp/generated_scripts/session_20260226_143022.py"
The AI looked up real examples, checked the actual function signature, executed working code, and gave the user both a live map and a saved script — all grounded in the real geeViz codebase rather than training data.
Example Questions to Try¶
Below are example prompts organized by category. These demonstrate the range of workflows the MCP server supports — from simple lookups to multi-step analyses with charting, reports, and map visualization.
Land Cover & Change Detection¶
“Show LCMS land cover time series for the Uinta-Wasatch-Cache National Forest from 1985-2024”
“Create a Sankey transition diagram of LCMS land use changes in Salt Lake County between 1990, 2005, and 2024”
“Run LANDTRENDR change detection near Bozeman, MT and show the loss year and magnitude”
“Compare Annual NLCD land cover between 1990 and 2024 for Denver metro area counties”
“Show LCMS Change (fast loss, slow loss, gain) as a stacked bar chart over Yellowstone”
Fire & Burn Severity¶
“Map MTBS burn severity for the 2020 Cameron Peak Fire — get the perimeter from EDW and show before/after Landsat”
“Chart MTBS burn severity trends across USFS ranger districts in the Wasatch Front from 2000-2024”
“Generate a report on fire activity in the Lolo National Forest with LCMS change, MTBS severity, and Sentinel-2 imagery”
Snow, Water & Climate¶
“Compare March snow cover using Sentinel-2 NDSI across 2017, 2019, 2023, and 2026 over the central Wasatch”
“Show MODIS snow cover duration trends for the Sierra Nevada from 2001-2024”
“Chart Palmer Drought Severity Index (PDSI) time series for the Great Plains from 2000-2024”
“Map Great Salt Lake extent change using NDWI from Landsat for 1990, 2000, 2015, and 2024”
Vegetation & Ecology¶
“Chart NDVI trends near Glacier National Park from 1990-2024 using Landsat summer composites”
“Show vegetation index time series (NDVI, NDMI) for the Sundarbans mangrove region”
“Compare forest canopy cover between USFS TreeMap and NLCD Tree Canopy Cover for a Colorado county”
Urban & Infrastructure¶
“Analyze urban heat island effect — compare MODIS LST between downtown Phoenix and surrounding rural areas”
“Chart VIIRS nighttime lights growth for Lagos, Nigeria from 2014-2024”
“Show impervious surface expansion using Annual NLCD for the Salt Lake City metro area”
Weather Forecasts¶
“Show the latest GFS temperature and precipitation forecast as a time-lapse”
“Compare WeatherNext Graph vs ECMWF IFS temperature forecasts for the next 5 days”
“Show WeatherNext 2 ensemble spread — where is forecast uncertainty highest?”
Thumbnails, Reports & Visualization¶
“Generate a filmstrip of LCMS land cover for 1990, 2000, 2010, 2020 over the San Juan National Forest with satellite basemap”
“Create an animated GIF of MTBS burn severity from 2015-2024 over California”
“Build a full report on the Wasatch Front with LCMS land cover, land use, burn severity, and Sentinel-2 imagery”
“Show me a Street View image at the summit of Snowbird ski resort and interpret what you see”
Ground-truthing & External Data¶
“Find coffee shops near the University of Utah campus”
“Get the elevation profile along a transect from Salt Lake City to Park City”
“Query the USFS EDW for fire perimeters in Montana from 2020-2024”
“Geocode ‘Bryce Canyon National Park’ and show LCMS land cover for the area”
Dataset Discovery & Inspection¶
“What datasets are available for global forest cover?”
“Inspect the COPERNICUS/S2_HARMONIZED collection — what bands does it have?”
“Find the latest LCMS version and show what bands and class properties it has”
“Search for drought-related datasets in the GEE catalog”