mcp-geo-server

An intelligent MCP (Model Context Protocol) server that lets you drive a GeoServer instance in natural language. It 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(). The LLM backend is pluggable — local Ollama, Ollama Cloud, or Anthropic Claude. Any MCP client sends a request like "how many features in topp:states?" and the agent decides which GeoServer operations to call.

Under the hood the agent can: manage workspaces, PostGIS datastores, feature types, layers and SLD styles via the REST API, and query/edit data via the OGC services (WMS, WFS GetFeature → GeoJSON, WFS-T insert/update/delete). It ships with a small Leaflet web UI and a Docker stack (GeoServer + PostGIS + Ollama) for local development.

The same async core (GeoServerClient + the geo_* tool functions) is shared by the agent and the web UI — there is exactly one place that talks to GeoServer.

Prerequisites

• Python 3.11+
• Docker + Docker Compose (for the local GeoServer/PostGIS stack)

1. Start the stack (Docker)

make build          # build the app image + pull GeoServer/PostGIS/Ollama
make ollama-pull    # download the LLM model into the Ollama container (once)
make docker-up      # start everything

The Compose project is named mcp-geo-server; containers are named coherently:

GeoServer runs with CORS_ENABLED=true so the browser UI can call OGC services directly. PostGIS has a healthcheck and GeoServer waits for it. The mcp agent talks to GeoServer and Ollama over the internal Compose network.

2. Install

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,webui]"
cp .env.example .env   # then edit as needed

3. Configuration (environment variables)

Secrets are never hardcoded — everything is read from the environment.

4. 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.

Choosing the LLM backend (GEO_LLM_PROVIDER)

Examples:

# Ollama Cloud
GEO_LLM_PROVIDER=ollama-cloud OLLAMA_API_KEY=sk-... OLLAMA_MODEL=gpt-oss:120b mcp-geo-server

# Anthropic Claude
GEO_LLM_PROVIDER=anthropic ANTHROPIC_API_KEY=sk-ant-... mcp-geo-server

For Docker, set the same variables in your shell (or .env) before make docker-up; the mcp service forwards them. With ollama-cloud/anthropic the local ollama container is not needed.

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)

For a stdio MCP client (claude_desktop_config.json), point command at mcp-geo-server and set the GEOSERVER_* / OLLAMA_* env vars.

5. Run the test UI

uvicorn webui.app:app --reload --port 8000

Open <http://localhost:8000>. The sidebar has a form for each operation (create workspace / PostGIS datastore, publish a feature type, create + assign a style, run a WFS query) plus a connection-status indicator. The map uses an OpenStreetMap basemap and shows selected layers as WMS overlays; the "Carica come GeoJSON" button fetches features via WFS and draws them with popups.

6. Tests

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

• tests/test_formatting.py, test_styles_helpers.py, test_ogc_helpers.py,

test_map_template.py — pure helpers / template rendering.

• tests/test_tools_behaviour.py — every tool driven with a FakeClient,

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

• tests/integration/test_live.py — status + create/list/delete workspace

round-trip; skipped unless GEO_RUN_INTEGRATION=1.

• tests/evals/geo_eval.xml — read-only eval questions against GeoServer's

standard sample data (e.g. topp:states has 49 features). Confirm the expected answers on your live instance.

Agent tools (28 geo_* functions)

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

The agent's instructions (agent.py) tell it to treat delete_* as destructive and only run them on explicit request.

Resilience knobs

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

502/503/504 — controlled by GEOSERVER_RETRIES and GEOSERVER_RETRY_BACKOFF.

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

with a suggested fix.

• OGC exceptions: ServiceExceptionReport / ServiceException (which arrive

with HTTP 200) are detected and raised with the response body.

• Logging on the mcp_geo_server logger (set GEO_LOG_LEVEL=DEBUG).

Project layout

src/mcp_geo_server/   core: config, client, formatting, agent (Agent Framework),
                      server (MCP stdio/http), tools/ (geo_* functions), templates/
webui/                FastAPI backend (app.py) + static Leaflet UI (static/index.html)
tests/                unit, behavioural, integration, evals
Dockerfile            app image (web UI + MCP agent)
docker-compose.yml    GeoServer 2.28.0 + PostGIS 16-3.4 + Ollama + webui + mcp