PyPI Downloads

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
• Prerequisites
• Installation
  • Docker Installation
  • pip Installation
  • Development Installation
• File Storage and --storage Usage
• 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
• Support
• Badges

🚀 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

1. Run geoserver-mcp:

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

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

1. Install uv package manager.

pip install uv

2. Create the Virtual Environment (Python 3.10+):

Linux/Mac:

uv venv --python=3.10

Windows PowerShell:

uv venv --python=3.10

3. Install the package using pip:

uv pip install geoserver-mcp

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

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

or

source .venv/bin/activate

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

Windows PowerShell:

.\.venv\Scripts\activate
geoserver-mcp

or

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

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

1. Install uv package manager.

pip install uv

2. Create the Virtual Environment (Python 3.10+):

uv venv --python=3.10

3. Install the package using pip:

uv pip install -e .

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

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

or

source .venv/bin/activate

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

Windows PowerShell:

.\.venv\Scripts\activate
geoserver-mcp

or

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

6. 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:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. 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