mcp-geo-server

An intelligent MCP (Model Context Protocol) server that drives a GeoServer instance in natural language, plus a chat + map web UI and a fully Dockerised, domain-agnostic GIS stack.

The MCP server is built with the Microsoft Agent Framework: an LLM-backed agent is given the GeoServer operations as tools and exposed as a single MCP tool via agent.as_mcp_server(). Any MCP client sends a request like "how many features in topp:states?" and the agent decides which GeoServer operations to call. The LLM backend is pluggable — host Ollama, Ollama Cloud, or Anthropic Claude.

Nothing in the code is tied to a specific dataset: the example stack ships the ISPRA landslide/hazard open data, but the catalog, the natural-language layer resolution and the thematic styles are all driven by GeoServer metadata and config, so the same stack serves any domain.

The same async core (GeoServerClient + the geo_* tool functions + the shared ingest/catalog/styling modules) is used by the agent, the web UI and the data bootstrap — there is exactly one place that talks to GeoServer.

mcp-geo-server — chat-first web UI: ask in natural language, the matching layers render on the map with a thematic legend

The chat (left) resolves a natural-language request to GeoServer layers and renders them on the map (right) with a thematic legend — here the landslide areas of the Marche region, classified by movement type.

Highlights

• 🧠 Natural-language GeoServer agent over MCP (stdio or streamable-HTTP).
• 💬 Chat-first web UI: ask in plain language, the matching layers render on a

Leaflet map with a live WMS legend. Shapefile upload on a dedicated page.

• 📦 Idempotent data bootstrap: drop shapefiles in ./data, the stack loads

them into PostGIS and publishes them as GeoServer layers automatically.

• 🎨 Config-driven thematic SLD styles (YAML) — no styles hardcoded in code.
• 🌍 Domain-agnostic: the layer catalog is read from the WMS capabilities;

style assignment is name-pattern based. Point it at any GeoServer.

• 🖥️ Native arm64 + amd64 images (no QEMU emulation on Apple Silicon), with a

per-architecture image switch in the Makefile.

• 🚀 CI/CD: a GitHub Action builds and publishes multi-arch images to GHCR.

Prerequisites

• Python 3.11+
• Docker + Docker Compose
• A host Ollama (https://ollama.com) for the local LLM — or use Ollama Cloud

/ Anthropic instead. There is no Ollama container; the stack talks to the host Ollama via host.docker.internal.

1. Start the stack (Docker)

ollama serve &            # start host Ollama (if not already running)
make ollama-pull          # pull the model onto the HOST Ollama (see OLLAMA_LLM_MODEL)
make build                # build the app images + pull GeoServer/PostGIS (per host arch)
make up                   # start the whole stack (checks host Ollama is reachable)

The Compose project is mcp-geo-server:

The LLM (host Ollama / Cloud / Anthropic) is reached lazily over the network, so it never gates startup. GeoServer runs with CORS_ENABLED=true; the web UI also proxies WMS (see below) so the browser never needs to reach GeoServer directly.

Native images & the per-architecture switch

Base images are multi-arch and selected by uname -m in the Makefile, so they run native (no emulation) on both Apple Silicon and Intel:

Override per run with POSTGIS_IMAGE / GEOSERVER_IMAGE / GEOSERVER_DATA_DIR. Bare docker compose (without make) defaults to the multi-arch images.

2. Web UI — chat & map

Open <http://localhost:8000>. The window is split: left = chat, right = a Leaflet/OpenStreetMap map with a WMS legend (bottom-right).

• Chat — type a request like "mostrami le frane lineari del Molise" or

"trova le frane in Puglia". An LLM resolves it to the matching published layer(s) (POST /api/ask); the map renders them as WMS overlays, zooms to their extent, shows the legend, and the assistant replies with a textual description of the data type (geometry kind, feature count, attributes). Empty layers are flagged and not drawn.

• ⬆️ Carica shapefile (dedicated page /upload) — drag-and-drop a .zip

shapefile; it is loaded into PostGIS (uploads workspace) and published (POST /api/upload).

WMS proxy

The UI talks to WMS only through the web UI (GET /wms), which forwards GetMap/GetLegendGraphic to GeoServer over the internal network and streams the bytes back. This keeps everything same-origin (no host/port juggling, no CORS), and retries on transient 429 so tiled overlays load reliably.

3. Data bootstrap & thematic styles

Bootstrap — the geo-init container loads every shapefile under ./data into PostGIS and publishes each as a GeoServer layer (default workspace ispra, datastore ispra_pg), reprojecting to EPSG:4326. It also registers every GeoTIFF (*.tif / *.tiff, e.g. a DTM/DEM) as an external coverage store — zero-copy: GeoServer reads the file in place through the shared ./data mount, the raster is never duplicated. Fully idempotent and transversal — no assumption about folder names; the layer name comes from the parent folder. It runs automatically on make up; re-run on demand:

make init          # load any new shapefiles + (re)apply styles
make init-force    # drop & reload tables that already exist
make styles        # only (re)apply the thematic styles
make init-logs     # tail the geo-init logs

Thematic styles are config-driven — no SLD is hardcoded. Styles and the layer→style assignment live in a YAML file, so the same engine serves any domain. The active config is data/styles.yml; if absent, the packaged mcp_geo_server/styles_default.yml (ISPRA landslide/hazard domain) is the fallback.

styles:                       # name -> SLD definition
  frana_tipo_poly:
    kind: polygon             # polygon | line | point | flat | outline | raster
    attribute: tipo_movim     # categorical: one rule per class
    stroke: true
    classes:
      - {value: "1", label: "Crollo / Ribaltamento", color: "#e41a1c"}
      # ...
  dtm_elevation:              # raster elevation ramp (RasterSymbolizer)
    kind: raster
    entries:
      - {quantity: 0, color: "#1a9850", label: "0 m"}
      - {quantity: 3500, color: "#ffffff", label: "3500 m"}
assign:                       # ordered rules, FIRST match wins (by layer name)
  - {name_matches: "^frane_line", style: frana_tipo_line}
  - {name_matches: "^(frane|aree|dgpv)_poly", style: frana_tipo_poly}
  - {name_contains: idraulica, style: pericolosita_idraulica}
  - {name_matches: "(dtm|dem)", style: dtm_elevation}

assign rules match a layer by name (name_contains substring or name_matches regex) — purely name-based, so the styling engine carries no hardcoded vocabulary. The patterns are domain-specific config, not code. To restyle for another domain, edit data/styles.yml and run make styles.

4. Natural-language layer resolution (domain-agnostic)

POST /api/ask maps a request to layers with no hardcoded vocabulary:

1. The catalog is built from the WMS GetCapabilities document — every

published layer's real name, title, abstract and keywords.

1. A lightweight LLM "resolver" (no GeoServer tools, JSON-only output) matches

the request against that metadata and returns the exact layer name(s), an optional cql_filter, and a short explanation. Hallucinated names are dropped against the catalog.

1. Filterable attributes (with their allowed values **and the layers they live

on*) are derived from the style config and passed to the resolver, so it builds a CQL on real values and picks a layer that actually has the attribute (e.g. `per_fr_ita = 'Elevata P3'` for "alta pericolosità"* → the hazard layer, not a landslide-inventory one).

The server does the rest — the response is ready for any map client:

• Draw order — layers come back bottom→top (rasters below vectors;

broadest raster lowest) with a kind per layer, so an opaque raster never hides the vectors.

• Admin-area scoping — if the request names a comune / provincia / regione

(ISTAT boundary layers), the response carries the zoom bbox and, per layer, the way to restrict it to that area: rasters get an exact-polygon clip, vectors get a CQL INTERSECTS spatial filter (a robust predicate — no geometry overlay, so no JTS non-noded intersection failure on dense layers).

• Per-layer CQL — cql_by_layer only applies a filter to layers that have

the attribute, so one filter can't fail the whole render.

• Terrain enrichment — if the request names a metric (quota / slope / aspect

/ curvature), the selected vector layers are enriched from a DTM (geo_enrich_from_dtm) and a ready-to-show summary is returned.

Because it relies on GeoServer metadata + config, it works for any GeoServer — just publish layers with meaningful titles/keywords (and, optionally, your own data/styles.yml).

5. The intelligent MCP server (Microsoft Agent Framework)

The MCP server is an agent, not a flat list of tools. server.py builds a GeoServer agent (agent.py: a chat client + the geo_* functions as tools) and exposes it with agent.as_mcp_server(). The MCP client therefore sees one tool, geoserver-agent, that takes a natural-language task.

Run it over either transport (selected by GEO_MCP_TRANSPORT):

# stdio (for MCP clients that spawn the process, e.g. Claude Desktop)
mcp-geo-server

# streamable-HTTP (long-lived, visible container) at http://localhost:9000/mcp
GEO_MCP_TRANSPORT=http mcp-geo-server

In Docker the mcp service runs it over HTTP. Example MCP client call:

from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

async with streamablehttp_client("http://localhost:9000/mcp") as (r, w, _):
    async with ClientSession(r, w) as s:
        await s.initialize()
        res = await s.call_tool("geoserver-agent",
                                {"task": "How many features are in topp:states?"})
        print(res.content[0].text)

Choosing the LLM backend (GEO_LLM_PROVIDER)

The ollama and ollama-cloud providers speak Ollama's own /api/chat protocol, not the OpenAI shape. An inference gateway that exposes /v1/chat/completions therefore needs GEO_LLM_PROVIDER=openai; pointing OLLAMA_HOST at it fails on the URL, before the model is ever consulted.

The model is read from `OLLAMA_LLM_MODEL` (falls back to OLLAMA_MODEL), or from `OPENAI_LLM_MODEL` under the openai provider. Put your per-machine config in `.env.local` (loaded by the Makefile and gitignored), e.g. OLLAMA_LLM_MODEL=llama3.2:3b.

6. Install (local dev, no Docker)

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,webui]"
cp .env.example .env.local   # then edit
uvicorn webui.app:app --reload --port 8000   # run the UI locally

7. Configuration (environment variables)

Data-bootstrap (GEO_INIT_*, GEO_STYLES_CONFIG, GEO_UPLOAD_*) and image (POSTGIS_IMAGE, GEOSERVER_IMAGE, GEOSERVER_DATA_DIR) knobs are documented in §3 and §1. Secrets are never hardcoded — everything is read from the environment.

8. Tests

pytest                                            # unit + behavioural (no GeoServer)
GEO_RUN_INTEGRATION=1 pytest tests/integration    # live round-trip vs real GeoServer

• test_formatting, test_styles_helpers, test_ogc_helpers, test_map_template

— pure helpers / template rendering.

• test_tools_behaviour — every tool driven with a FakeClient, asserting on

request bodies / params / WFS-T XML (no network).

• test_catalog — WMS-capabilities parsing + LLM-selection validation.
• test_styling — config-driven SLD generation + name-based style assignment.
• tests/integration/test_live.py — skipped unless GEO_RUN_INTEGRATION=1.
• tests/evals/geo_eval.xml — read-only eval questions against sample data.

9. CI/CD — published images (GHCR)

.github/workflows/docker-publish.yml runs on push to main and on v* tags: it runs the test suite, then builds and pushes multi-arch (amd64 + arm64) images to the GitHub Container Registry:

Agent tools (33 geo_* functions)

These are the tools the agent calls internally (they are not exposed individually over MCP — the agent is). make tools lists them.

Destructive-operation safety

A Microsoft Agent Framework function middleware (middleware.py, DestructiveGuard) intercepts destructive tools (geo_delete_* and geo_wfs_transaction). Unless GEO_ALLOW_DESTRUCTIVE=true, the call is short-circuited and the agent reports a refusal instead of mutating data — a deterministic guard that works even though the MCP server is non-interactive.

Resilience

• Retry with linear backoff on connect errors, timeouts, and HTTP

502/503/504 (GEOSERVER_RETRIES, GEOSERVER_RETRY_BACKOFF); the WMS proxy also retries on 429.

• Actionable errors: 401/403/404/405/409/500 translated into messages with a

suggested fix.

• OGC exceptions: ServiceExceptionReport (HTTP 200) detected and raised.
• Logging on the mcp_geo_server logger (GEO_LOG_LEVEL=DEBUG).

Project layout

src/mcp_geo_server/
  config.py        settings from env (incl. public URL, providers)
  client.py        async GeoServer HTTP client (auth, retry, OGC helpers)
  agent.py         Microsoft Agent Framework agent (pluggable LLM)
  server.py        MCP server (stdio / streamable-HTTP)
  tools/           the geo_* tool functions
  ingest.py        shared shapefile -> PostGIS -> publish core
  bootstrap.py     batch loader over ./data (compose service geo-init)
  catalog.py       domain-agnostic catalog (WMS caps) + NL-selection validation
  styling.py       config-driven SLD engine + name-based assignment
  styles_default.yml  default (ISPRA) style config
webui/
  app.py           FastAPI backend (chat /api/ask, /api/upload, /wms proxy, …)
  static/          chat+map UI (index.html) + upload page (upload.html)
data/              your shapefiles + optional styles.yml (gitignored)
tests/             unit, behavioural, catalog, styling, integration, evals
Dockerfile         multi-stage: base (app) + bootstrap (adds GDAL/psql)
docker-compose.yml postgis + geoserver + geo-init + webui + mcp
.github/workflows/ docker-publish.yml — build & push multi-arch images to GHCR