geoserver-mcp MCP Server

GeoServer MCP Server

A Model Context Protocol (MCP) server implementation that connects Large Language Models (LLMs) to the GeoServer REST API, enabling AI assistants to interact with geospatial data and services.

Version 0.5.0 (Beta) is under active development and will be released shortly. We are open to contributions and welcome developers to join us in building this project.

🎥 Demo

📋 Table of Contents

🚀 Features

🔍 Query and manipulate GeoServer workspaces, layers, and styles
🗺️ Execute spatial queries on vector data
🎨 Generate map visualizations
🌐 Access OGC-compliant web services (WMS, WFS)
🛠️ Easy integration with MCP-compatible clients

📋 Prerequisites

Python 3.10 or higher
Running GeoServer instance with REST API enabled
MCP-compatible client (like Claude Desktop or Cursor)
Internet connection for package installation

🛠️ Installation

Choose the installation method that best suits your needs:

Installing via Smithery

To install GeoServer MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @mahdin75/geoserver-mcp --client claude

🛠️ Installation (Docker)

The Docker installation is the quickest and most isolated way to run the GeoServer MCP server. It's ideal for:

Quick testing and evaluation
Production deployments
Environments where you want to avoid Python dependencies
Consistent deployment across different systems

Run geoserver-mcp:

docker pull mahdin75/geoserver-mcp
docker run -d mahdin75/geoserver-mcp

Configure the clients:

If you are using Claude Desktop, edit claude_desktop_config.json If you are using Cursor, Create .cursor/mcp.json

{
  "mcpServers": {
    "geoserver-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GEOSERVER_URL=http://localhost:8080/geoserver",
        "-e",
        "GEOSERVER_USER=admin",
        "-e",
        "GEOSERVER_PASSWORD=geoserver",
        "-p",
        "8080:8080",
        "mahdin75/geoserver-mcp"
      ]
    }
  }
}

🛠️ Installation (pip)

The pip installation is recommended for most users who want to run the server directly on their system. This method is best for:

Regular users who want to run the server locally
Systems where you have Python 3.10+ installed
Users who want to customize the server configuration
Development and testing purposes

Install uv package manager.

pip install uv

Create the Virtual Environment (Python 3.10+):

Linux/Mac:

uv venv --python=3.10

Windows PowerShell:

uv venv --python=3.10

Install the package using pip:

uv pip install geoserver-mcp

Configure GeoServer connection:

Linux/Mac:

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"

Start the server:

If you are going to use Claude desktop you don't need this step. For cursor or your own custom client you should run the following code.

Linux:

source .venv/bin/activate

geoserver-mcp

source .venv/bin/activate

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

Windows PowerShell:

.\.venv\Scripts\activate
geoserver-mcp

.\.venv\Scripts\activate
geoserver-mcp --url http://localhost:8080/geoserver --user admin --password geoserver --debug

Configure Clients:

If you are using Claude Desktop, edit claude_desktop_config.json If you are using Cursor, Create .cursor/mcp.json

Windows:

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

Linux:

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

🛠️ Development installation

The development installation is designed for contributors and developers who want to modify the codebase. This method is suitable for:

Developers contributing to the project
Users who need to modify the source code
Testing new features
Debugging and development purposes

Install uv package manager.

pip install uv

Create the Virtual Environment (Python 3.10+):

uv venv --python=3.10

Install the package using pip:

uv pip install -e .

Configure GeoServer connection:

Linux/Mac:

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"

Start the server:

If you are going to use Claude desktop you don't need this step. For cursor or your own custom client you should run the following code.

Linux:

source .venv/bin/activate

geoserver-mcp

source .venv/bin/activate

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

Windows PowerShell:

.\.venv\Scripts\activate
geoserver-mcp

.\.venv\Scripts\activate
geoserver-mcp --url http://localhost:8080/geoserver --user admin --password geoserver --debug

Configure Clients:

If you are using Claude Desktop, edit claude_desktop_config.json If you are using Cursor, Create .cursor/mcp.json

Windows:

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

Linux:

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

File Storage and --storage Usage

GeoServer MCP server supports an optional --storage flag to specify a base directory for all file read/write operations, such as uploading shapefiles, GeoTIFFs, or exporting results.

Overview

The --storage flag sets the root folder for file operations from all data-related tools.
You may supply relative paths (relative to storage root) or absolute paths (bypassing the storage root) as arguments to relevant tools.
If --storage is not set, paths are resolved as provided by the user (relative to working directory or absolute).

CLI Example

python -m geoserver_mcp.main --storage D:/my/data/dir

This sets D:/my/data/dir as the base path for all files.

Example tool call in Python:

# Will read from D:/my/data/dir/roads.zip if --storage is set to D:/my/data/dir
create_shp_datastore('workspace', 'datastore_name', 'roads.zip')

Absolute paths (e.g. 'C:/input/other.shp') are always used as-is.

When Running in Docker

If using Docker, ensure the storage directory is mounted as a volume, e.g.:

docker run -v D:/my/data:/opt/data ...

Then launch the server with:

python -m geoserver_mcp.main --storage /opt/data

Best Practices

Use relative paths when interacting with the API/tools as it keeps your setup portable.
For remote or container deployment, always ensure your file data is accessible within the container (use Docker volumes if needed).
Check tool docstrings for which arguments use the storage system.

The --storage system streamlines file management for all users and makes deployment much more flexible!

🛠️ Available Tools

This section details all the available tools and resources exposed by the GeoServer MCP server. These tools allow LLMs to interact with GeoServer's REST API for comprehensive geospatial data management.

🌍 Resource Endpoints

Resource endpoints provide direct access to GeoServer resources via a URI pattern.

Resource URI	Description
`geoserver://catalog/workspaces`	List available workspaces
`geoserver://catalog/layers/{workspace}/{layer}`	Get information about a specific layer
`geoserver://services/wms/{request}`	Handle WMS resource requests
`geoserver://services/wfs/{request}`	Handle WFS resource requests

📦 Workspace Management

Tool	Description
`list_workspaces`	List available workspaces in GeoServer
`create_workspace`	Create a new workspace in GeoServer

📁 Datastore & Coveragestore Management

Tool	Description
`create_datastore`	Create a new datastore in the given workspace
`create_featurestore`	Create a new featurestore in the given workspace
`create_gpkg_datastore`	Create a GeoPackage (GPKG) datastore
`create_shp_datastore`	Create an ESRI Shapefile datastore
`create_coveragestore`	Create a new coveragestore in a workspace
`delete_coveragestore`	Delete a coveragestore from a workspace
`get_coveragestore`	Get details about a single coveragestore
`get_coveragestores`	Get all coveragestores for a workspace
`get_datastore`	Get a specific datastore by name
`get_datastores`	List all datastores in the given workspace

🗺️ Layer Management

Tool	Description
`get_layer_info`	Get detailed information about a layer
`list_layers`	List layers in GeoServer, optionally filtered by workspace
`create_layer`	Create a new layer in GeoServer
`delete_resource`	Delete a resource from GeoServer (generic)

🧩 Layer Group Management

Tool	Description
`create_layergroup`	Create a new layer group with specific layers and (optionally) styles
`get_layergroup`	Get a layer group from a workspace
`get_layergroups`	List all layer groups in a workspace
`add_layer_to_layergroup`	Add a specific layer to a layer group
`remove_layer_from_layergroup`	Remove a layer from a group
`delete_layergroup`	Delete a layer group from a workspace
`update_layergroup`	Update a layer group's details and configuration

👥 User & User Group Management

Tool	Description
`create_user`	Create a new user for GeoServer security
`delete_user`	Delete a user by name
`get_all_users`	List all users in the GeoServer instance
`modify_user`	Modify an existing user's properties
`create_usergroup`	Create a new user group
`delete_usergroup`	Delete a user group
`get_all_usergroups`	Return all user groups

📊 Feature Type & Attribute Management

Tool	Description
`query_features`	Query features from a vector layer using CQL filter
`publish_featurestore`	Publish an existing featurestore
`publish_featurestore_sqlview`	Publish a featurestore using a SQL view definition
`edit_featuretype`	Edit the settings of a feature type in a store
`get_featuretypes`	List all feature types in a given store
`get_feature_attribute`	Get feature attribute schema/details

🎨 Style Management

Tool	Description
`create_style`	Create a new SLD style in GeoServer
`publish_style`	Assign/publish a style to a layer
`create_catagorized_featurestyle`	Create a categorized style for features
`create_classified_featurestyle`	Create a classified style for features
`create_coveragestyle`	Create a raster coverage style
`create_outline_featurestyle`	Create a simple outline-only style for features

⚙️ System & Service Operations

Tool	Description
`get_manifest`	Get GeoServer manifest metadata/details
`get_status`	Obtain general server status
`get_system_status`	Get system status overview/info from GeoServer
`get_version`	Fetch GeoServer version string
`reload_geoserver`	Reload catalog and config from disk
`reset_geoserver`	Reset all GeoServer caches/connections
`update_service`	Update selected OGC service options
`publish_time_dimension_to_coveragestore`	Add or update a time dimension for a coverage store (for time series)

📝 Style XML Utilities

Tool	Description
`style_catagorize_xml`	Generate SLD for categorized vector style
`style_classified_xml`	Get SLD XML for classified vector style
`style_coverage_style_colormapentry`	Generate color map entries for raster SLD
`style_coverage_style_xml`	Generate XML for raster/coverage SLD
`style_outline_only_xml`	XML for outline-only style for a geometry

🛠️ Client Development

If you're planning to develop your own client to interact with the GeoServer MCP server, you can find inspiration in the example client implementation at examples/client.py. This example demonstrates:

How to establish a connection with the MCP server
How to send requests and handle responses
Basic error handling and connection management
Example usage of various tools and operations

The example client serves as a good starting point for understanding the protocol and implementing your own client applications.

Also, here is the example usgage:

List Workspaces


Tool: list_workspaces
Parameters: {}
Response: ["default", "demo", "topp", "tiger", "sf"]

Get Layer Information


Tool: get_layer_info
Parameters: {
"workspace": "topp",
"layer": "states"
}

Query Features


Tool: query_features
Parameters: {
"workspace": "topp",
"layer": "states",
"filter": "PERSONS > 10000000",
"properties": ["STATE_NAME", "PERSONS"]
}

Generate Map


Tool: generate_map
Parameters: {
"layers": ["topp:states"],
"styles": ["population"],
"bbox": [-124.73, 24.96, -66.97, 49.37],
"width": 800,
"height": 600,
"format": "png"
}

🔮 Planned Features

Coverage and raster data management
Security and access control
Advanced styling capabilities
WPS processing operations
GeoWebCache integration

🤝 Contributing

We welcome contributions! Here's how you can help:

Fork the repository
Create a feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Please ensure your PR description clearly describes the problem and solution. Include the relevant issue number if applicable.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Projects

Model Context Protocol - The core MCP implementation
GeoServer REST API - Official GeoServer REST documentation
GeoServer REST Python Client - Python client for GeoServer REST API

🌐 See Also: GIS MCP

For broader geospatial data automation and even more GIS-related MCP features, see GIS MCP by mahdin75.

📞 Support

For support, please Open an issue

🏆 Badges

{ "mcpServers": { "geoserver-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "GEOSERVER_URL=http://localhost:8080/geoserver", "-e", "GEOSERVER_USER=admin", "-e", "GEOSERVER_PASSWORD=geoserver", "-p", "8080:8080", "mahdin75/geoserver-mcp" ] } } }

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

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

Resource URI

Description

geoserver://catalog/workspaces

List available workspaces

geoserver://catalog/layers/{workspace}/{layer}

Get information about a specific layer

geoserver://services/wms/{request}

Handle WMS resource requests

geoserver://services/wfs/{request}

Handle WFS resource requests

Tool

Description

list_workspaces

List available workspaces in GeoServer

create_workspace

Create a new workspace in GeoServer

Tool

Description

create_datastore

Create a new datastore in the given workspace

create_featurestore

Create a new featurestore in the given workspace

create_gpkg_datastore

Create a GeoPackage (GPKG) datastore

create_shp_datastore

Create an ESRI Shapefile datastore

create_coveragestore

Create a new coveragestore in a workspace

delete_coveragestore

Delete a coveragestore from a workspace

get_coveragestore

Get details about a single coveragestore

get_coveragestores

Get all coveragestores for a workspace

get_datastore

Get a specific datastore by name

get_datastores

List all datastores in the given workspace

Tool

Description

get_layer_info

Get detailed information about a layer

list_layers

List layers in GeoServer, optionally filtered by workspace

create_layer

Create a new layer in GeoServer

delete_resource

Delete a resource from GeoServer (generic)

Tool

Description

create_layergroup

Create a new layer group with specific layers and (optionally) styles

get_layergroup

Get a layer group from a workspace

get_layergroups

List all layer groups in a workspace

add_layer_to_layergroup

Add a specific layer to a layer group

remove_layer_from_layergroup

Remove a layer from a group

delete_layergroup

Delete a layer group from a workspace

update_layergroup

Update a layer group's details and configuration

Tool

Description

create_user

Create a new user for GeoServer security

delete_user

Delete a user by name

get_all_users

List all users in the GeoServer instance

modify_user

Modify an existing user's properties

create_usergroup

Create a new user group

delete_usergroup

Delete a user group

get_all_usergroups

Return all user groups

Tool

Description

query_features

Query features from a vector layer using CQL filter

publish_featurestore

Publish an existing featurestore

publish_featurestore_sqlview

Publish a featurestore using a SQL view definition

edit_featuretype

Edit the settings of a feature type in a store

get_featuretypes

List all feature types in a given store

get_feature_attribute

Get feature attribute schema/details

Tool

Description

create_style

Create a new SLD style in GeoServer

publish_style

Assign/publish a style to a layer

create_catagorized_featurestyle

Create a categorized style for features

create_classified_featurestyle

Create a classified style for features

create_coveragestyle

Create a raster coverage style

create_outline_featurestyle

Create a simple outline-only style for features

Tool

Description

get_manifest

Get GeoServer manifest metadata/details

get_status

Obtain general server status

get_system_status

Get system status overview/info from GeoServer

get_version

Fetch GeoServer version string

reload_geoserver

Reload catalog and config from disk

reset_geoserver

Reset all GeoServer caches/connections

update_service

Update selected OGC service options

publish_time_dimension_to_coveragestore

Add or update a time dimension for a coverage store (for time series)

Tool

Description

style_catagorize_xml

Generate SLD for categorized vector style

style_classified_xml

Get SLD XML for classified vector style

style_coverage_style_colormapentry

Generate color map entries for raster SLD

style_coverage_style_xml

Generate XML for raster/coverage SLD

style_outline_only_xml

XML for outline-only style for a geometry

geoserver-mcp

README Documentation

GeoServer MCP Server

🎥 Demo

📋 Table of Contents

🚀 Features

📋 Prerequisites

🛠️ Installation

Installing via Smithery

🛠️ Installation (Docker)

🛠️ Installation (pip)

🛠️ Development installation

File Storage and --storage Usage

Overview

CLI Example

When Running in Docker

Best Practices

🛠️ Available Tools

🌍 Resource Endpoints

📦 Workspace Management

📁 Datastore & Coveragestore Management

🗺️ Layer Management

🧩 Layer Group Management

👥 User & User Group Management

📊 Feature Type & Attribute Management

🎨 Style Management

⚙️ System & Service Operations

📝 Style XML Utilities

🛠️ Client Development

List Workspaces

Get Layer Information

Query Features

Generate Map

🔮 Planned Features

🤝 Contributing

📄 License

🔗 Related Projects

🌐 See Also: GIS MCP

📞 Support

🏆 Badges

Quick Install

Quick Actions

Key Features

geoserver-mcp

README Documentation

GeoServer MCP Server

🎥 Demo

📋 Table of Contents

🚀 Features

📋 Prerequisites

🛠️ Installation

Installing via Smithery

🛠️ Installation (Docker)

🛠️ Installation (pip)

🛠️ Development installation

File Storage and --storage Usage

Overview

CLI Example

When Running in Docker

Best Practices

🛠️ Available Tools

🌍 Resource Endpoints

📦 Workspace Management

📁 Datastore & Coveragestore Management

🗺️ Layer Management

🧩 Layer Group Management

👥 User & User Group Management

📊 Feature Type & Attribute Management

🎨 Style Management

⚙️ System & Service Operations

📝 Style XML Utilities

🛠️ Client Development

List Workspaces

Get Layer Information

Query Features

Generate Map

🔮 Planned Features

🤝 Contributing

📄 License

🔗 Related Projects