GeoServer MCP Server

<p align="center">
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.

</p>

<div align="center">

</div>

> 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

<div align="center">

</div>

📋 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:

```python