Startseite / Artikel / KI-Agenten über die MCP-Erweiterung mit GeoServer 2.28 verbinden

geoservermcpai-agentsgislangchain

KI-Agenten über die MCP-Erweiterung mit GeoServer 2.28 verbinden

Das JAR der GeoServer-MCP-Erweiterung installieren, prüfen, ob es geladen wurde, den Endpunkt mit curl aufrufen, Claude Desktop oder LangChain anbinden und Zugriff sowie Schreib-Tools absichern.

1377 Wörter

KI-Agenten einen Live-Blick auf GeoServer geben

Eine Erweiterung und ein Neustart reichen, damit ein Agent Ihren Katalog per MCP abfragen kann. Kein Python-Sidecar, kein zusätzlicher Docker-Container. Diese Notizen beziehen sich auf Version 0.1.0 der GeoServer MCP Extension und GeoServer 2.28.x. Sie wird als Pre-Release-JAR auf GitHub ausgeliefert und ersetzt nicht das Paket geoserver-mcp auf PyPI.

Was die Erweiterung macht

Es ist ein ganz normales GeoServer-Plugin. Sobald das JAR in GeoServer liegt und der Server neu gestartet wurde, spricht GeoServer selbst MCP unter dieser Adresse:

http://127.0.0.1:8080/geoserver/mcp

Agenten schicken JSON-RPC über HTTP (Streamable HTTP), und GeoServer antwortet aus seinem eigenen Katalog. Die Ergebnisse laufen weiterhin durch die Sicherheitsregeln von GeoServer.

Die Tool-Namen für Katalogarbeit (list, get, query, create, delete, publish) sind dieselben wie beim Python-MCP-Server. Die administrativen Extras des Python-Pakets (Benutzerverwaltung, Reload, Datei-Uploads) sind nicht mit dabei – dazu mehr weiter unten bei den typischen Fehlern.

Schreib-Tools sind standardmäßig aktiviert. Für einen reinen Lese-Endpunkt tragen Sie mcp.allowWrites=false in die Konfiguration des Datenverzeichnisses ein.

Unter Windows schreiben Sie 127.0.0.1 statt localhost. Einige Python-MCP-Clients machen aus localhost die IPv6-Adresse ::1 und bekommen HTTP 503, obwohl die IPv4-Route einwandfrei funktioniert.

Voraussetzungen

  • GeoServer 2.28.x auf Java 17 oder 21
  • Ein GeoServer-Benutzer (eine frische Installation bringt admin / geoserver mit)
  • Das JAR der Erweiterung, dazu gleich mehr

Lassen Sie dieses JAR aus GeoServer 2.20.x und 3.x heraus. Version 2.20 läuft auf Java 11, startet nicht und liefert HTTP 503. GeoServer 3 ist auf Jakarta Servlet umgestiegen, dort lädt dieser Build nicht. Wenn Sie ein älteres GeoServer noch für andere Aufgaben brauchen, lassen Sie es in Ruhe und setzen Sie für das Plugin eine separate 2.28-Installation auf.

Das JAR besorgen

Sie brauchen die Datei gs-mcp-0.1.0.jar, die als GitHub-Release veröffentlicht ist, der Download-Link lautet https://download.gis-mcp.com/geoserver-mcp-extension, legen Sie sie an einem griffbereiten Ort ab, etwa im Download-Ordner. Sie können sie auch selbst bauen oder aus dem Repository https://github.com/mahdin75/geoserver-mcp holen.

Installation

  1. Öffnen Sie GeoServer und schauen Sie unter About & Status, dann About GeoServer nach. Die Version muss mit 2.28 beginnen.
  2. Stoppen Sie GeoServer.
  3. Kopieren Sie gs-mcp-0.1.0.jar in den Ordner WEB-INF/lib der Web-App. Beim Binär-/Jetty-Paket ist das <GEOSERVER_ROOT>/webapps/geoserver/WEB-INF/lib, bei Tomcat <CATALINA_BASE>/webapps/geoserver/WEB-INF/lib.

Unter Windows sieht der endgültige Pfad oft so aus:

D:\geoserver-2.28.5\webapps\geoserver\WEB-INF\lib\gs-mcp-0.1.0.jar

Danach starten Sie den Server wieder:

Start GeoServer.

Eine web.xml müssen Sie nicht anfassen, GeoServer erkennt das Plugin von selbst.

Prüfen, ob es geladen wurde

  1. Öffnen Sie http://127.0.0.1:8080/geoserver/web/ und melden Sie sich an.
  2. Gehen Sie zu About & Status, dann Modules.
  3. Suchen Sie nach GeoServer MCP Extension (gs-mcp).

Liefert nach dem Kopieren schon die Weboberfläche 503, ist das JAR im falschen GeoServer gelandet. Entfernen Sie es, starten Sie neu und installieren Sie es in eine 2.28.x-Instanz.

Den Endpunkt aufrufen

Das Plugin sitzt unter /mcp innerhalb der GeoServer-Web-App. Bei einem unter /geoserver eingehängten GeoServer lautet die öffentliche URL also /geoserver/mcp. Ab Werk ist eine Anmeldung nötig, per HTTP Basic mit einem echten GeoServer-Benutzer. In der Windows PowerShell rufen Sie curl.exe auf, denn ein schlichtes curl ist dort ein anderer Befehl.

Initialize

curl.exe -s -u admin:geoserver \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-03-26" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{},\"clientInfo\":{\"name\":\"curl\",\"version\":\"1.0\"}}}" \
  http://127.0.0.1:8080/geoserver/mcp

Tools auflisten

curl.exe -s -u admin:geoserver \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-03-26" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\"}" \
  http://127.0.0.1:8080/geoserver/mcp

In der Antwort sollten rund 30 Katalog-Tools stehen, zum Beispiel list_workspaces, list_layers, create_workspace und query_features.

Layer auflisten

curl.exe -s -u admin:geoserver \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-03-26" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"list_layers\",\"arguments\":{}}}" \
  http://127.0.0.1:8080/geoserver/mcp

Drei schnelle Plausibilitätschecks:

  • Ein POST mit -u admin:geoserver liefert ein JSON-Ergebnis.
  • Ein POST ohne Benutzer liefert HTTP 401.
  • Ein GET auf /geoserver/mcp liefert HTTP 405.

Einen KI-Client anbinden

Ein Client muss nur JSON per POST an eine URL schicken können. Claude Desktop und LangChain sind nicht ins Plugin eingebaut, Sie richten den Client also einfach auf GeoServer aus.

Claude Desktop

Lokale MCP-Server erreichen Claude Desktop über stdio, dieses Plugin ist aber ein HTTP-Dienst. Eine kleine Brücke namens mcp-remote verbindet beides. Sie braucht Node.js, damit npx verfügbar ist.

  1. Öffnen Sie Settings, dann Developer, dann Edit Config. Dadurch öffnet sich claude_desktop_config.json. Unter Windows liegt die Datei unter %APPDATA%\Claude\claude_desktop_config.json, unter macOS unter ~/Library/Application Support/Claude/claude_desktop_config.json.
  2. Fügen Sie den folgenden Server hinzu und behalten Sie vorhandene mcpServers-Einträge bei:
{
  "mcpServers": {
    "geoserver": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8080/geoserver/mcp",
        "--allow-http",
        "--header",
        "Authorization:Basic YWRtaW46Z2Vvc2VydmVy"
      ]
    }
  }
}

YWRtaW46Z2Vvc2VydmVy ist admin:geoserver in Base64. Tauschen Sie es aus, wenn Ihr Passwort vom Standard abweicht. Das Flag --allow-http ist nötig, weil ein lokaler GeoServer schlichtes HTTP spricht und kein HTTPS.

  1. Beenden Sie Claude Desktop vollständig und öffnen Sie es erneut.
  2. Testen Sie mit einem Prompt wie „Welche Workspaces gibt es auf diesem GeoServer?“ oder „Lege einen Workspace namens demo_mcp an und zeig mir dann die Layer in topp.“

Tauchen die Tools nicht auf, prüfen Sie zuerst, ob der Server läuft und ob der curl-POST von oben mit -u admin:geoserver durchgeht.

LangChain

Los geht es mit dem Import:

from langchain_mcp_adapters.client import MultiServerMCPClient

Dann legen Sie den Client an:

client = MultiServerMCPClient(
    {
        "geoserver": {
            "transport": "streamable_http",
            "url": "http://127.0.0.1:8080/geoserver/mcp",
            "headers": {"Authorization": "Basic YWRtaW46Z2Vvc2VydmVy"},
        }
    }
)
tools = await client.get_tools()

Wird streamable_http abgelehnt, versuchen Sie stattdessen "transport": "http". URL und Basic-Header bleiben gleich.

Das Projekt bringt einen Smoke-Test als extension/examples/langchain_mcp_test.py mit:

pip install -r extension/examples/requirements-langchain.txt
python extension/examples/langchain_mcp_test.py --url http://127.0.0.1:8080/geoserver/mcp

Das Skript hat einen optionalen Schalter --agent, der zusätzlich einen LangChain-Agenten über OpenRouter startet. Dafür muss OPENROUTER_API_KEY gesetzt sein. Nötig ist Python 3.10.11 oder neuer (3.11+ geht auch). Frühe 3.10.0-Builds scheitern beim Verbinden mit OpenRouter oft an TLS.

Anonyme Nutzer aussperren

Die Authentifizierung ist standardmäßig aktiv. Feinjustieren lässt sie sich über eine optionale Datei mcp.properties im GeoServer-Datenverzeichnis:

mcp.enabled=true
mcp.path=/mcp
mcp.requireAuthentication=true
mcp.allowWrites=true
mcp.maxFeatures=100

Mit mcp.requireAuthentication=true bekommt eine Anfrage ohne Anmeldung HTTP 401, eine Anfrage mit GeoServer-Benutzer führt Tools aus. Dieser Benutzer sieht und ändert trotzdem nur, was die Datensicherheit von GeoServer erlaubt.

Lassen Sie den Wert auf true, es sei denn, anonyme Aufrufer sollen wirklich an öffentliche Katalogobjekte herankommen. Mit mcp.allowWrites=false verschwinden die Schreib-Tools aus tools/list und werden in tools/call abgewiesen. Nach jeder Änderung an mcp.properties starten Sie GeoServer neu.

Fehler, über die man stolpert

  • Falsche GeoServer-Reihe. Das JAR funktioniert nur auf 2.28.x, unter 2.20.x startet die Web-App nicht.
  • Falsches Java. GeoServer 2.28 braucht Java 17 oder 21, mit Java 11 lädt das Plugin nicht.
  • Kein Neustart nach dem Kopieren des JAR.
  • Fehlender Authorization-Header. Die Standardkonfiguration antwortet mit 401.
  • localhost unter Windows. Python-MCP-Clients gehen eventuell über IPv6 und landen bei 503, nehmen Sie also http://127.0.0.1:8080/geoserver/mcp.
  • Ein Workspace namens mcp. Wählen Sie einen anderen Namen, sonst kann er mit dem Pfad /mcp kollidieren.
  • Administrative Tools erwarten. Shapefile-Uploads, SQL-Views, Reloads und Benutzerverwaltung fehlen in diesem Plugin komplett.
  • TLS-Fehler mit --agent. Unter Python 3.10.0 kann der GeoServer-Teil des Smoke-Tests klappen, während der OpenRouter-Aufruf abstürzt. Wechseln Sie also auf 3.10.11 oder 3.11+.

Wo der Code liegt

Der Quellcode liegt unter https://github.com/mahdin75/geoserver-mcp (im Ordner extension). Der Build 0.1.0 hat eine eigene Release-Seite, https://github.com/mahdin75/geoserver-mcp/releases/tag/extension-v0.1.0, und im selben Repository werden auch Issues und Pull Requests angenommen.

Der ganze Ablauf in Kürze: JAR holen, in WEB-INF/lib einer 2.28-Installation legen, neu starten und dann mit gültigen GeoServer-Zugangsdaten per POST an /geoserver/mcp gehen.

Alle ArtikelBrief senden