geoserver

GeoServer MCP Server connects LLMs to a GeoServer REST API, enabling AI assistants to interact with geospatial data and services. It exposes a rich set of MCP-compatible tools for working with GeoServer resources and configurations, including workspaces, datastores, layers, styles, and maps. The server supports querying and manipulating resources, executing spatial queries, generating map outputs, and interacting with OGC services (WMS, WFS). You can configure clients (Claude Desktop, Cursor, or custom MCP clients) to discover and utilize these endpoints through the provided MCP configuration payloads. Typical workflows include retrieving layer metadata, updating layer styles, running spatial queries against vector data, and generating map previews via the MCP interface.

Prerequisites:

• Python 3.10 or higher
• Access to a GeoServer instance with REST API enabled
• Internet access to install Python packages

Installation steps:

1. Install the uv package manager (Python utility used by this project):

pip install uv

2. Create a Python virtual environment for the project (Python 3.10+):

uv venv --python=3.10

3. Install the GeoServer MCP package in editable/standard mode:

uv pip install geoserver-mcp

4. Configure GeoServer connection (set environment variables):

Linux/macOS:

export GEOSERVER_URL="http://localhost:8080/geoserver"
export GEOSERVER_USER="admin"
export GEOSERVER_PASSWORD="geoserver"

Windows PowerShell:

$env:GEOSERVER_URL="http://localhost:8080/geoserver"
$env:GEOSERVER_USER="admin"
$env:GEOSERVER_PASSWORD="geoserver"

5. Start the server (for clients like Cursor or custom MCP clients):

Linux:

source .venv/bin/activate
geoserver-mcp

or with explicit connection parameters:

geoserver-mcp --url http://localhost:8080/geoserver --user admin --password geoserver --debug

Windows PowerShell:

.
venv\Scripts\activate
geoserver-mcp

or with explicit connection parameters:

.geoserver-mcp --url http://localhost:8080/geoserver --user admin --password geoserver --debug

6. Configure MCP client integrations:

Claude Desktop: edit claude_desktop_config.json Cursor: create/modify .cursor/mcp.json with the geoserver-mcp configuration, including command and arguments as shown in the examples above.

Example client configuration (Linux):

{
  "mcpServers": {
    "geoserver-mcp": {
      "command": "/path/to/geoserver-mcp/.venv/bin/geoserver-mcp",
      "args": [
        "--url",
        "http://localhost:8080/geoserver",
        "--user",
        "admin",
        "--password",
        "geoserver"
      ]
    }
  }
}

7. Optional: for development, install in editable mode and run from source after cloning the repo, then configure environment variables similarly.

Tips and caveats:

• Ensure GeoServer REST API is enabled and reachable at the configured GEOSERVER_URL.
• Keep GEOSERVER_PASSWORD secure; consider using a secrets manager or environment secrets in your deployment environment.
• The MCP payloads expect a structure under mcpServers with command, args, and optional env fields; adapt the example to your client configuration if needed.
• When running in Docker, you can map ports (8080) and pass credentials via environment variables or client config as shown in the README examples.
• If you switch clients (Claude vs Cursor), update claude_desktop_config.json or .cursor/mcp.json accordingly to ensure proper authentication and endpoint usage.
• Use the --debug flag during initial connections to help diagnose authentication or connectivity issues.
• For development or testing, you can point the MCP server to a local GeoServer instance to avoid network latency and simplify debugging.