geoserver-mcp

Version 0.4.0 (Alpha) 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
• Available Tools
  • Workspace and Layer Management
  • Data Operations
  • Visualization
• 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"
      ]
    }
  }
}

🛠️ Available Tools

🛠️ Workspace and Layer Management

| Tool | Description | | ------------------ | --------------------------- | | list_workspaces | Get available workspaces | | create_workspace | Create a new workspace | | get_layer_info | Get detailed layer metadata | | list_layers | List layers in a workspace | | create_layer | Create a new layer | | delete_resource | Remove resources |

🛠️ Data Operations

| Tool | Description | | ----------------- | ---------------------------------- | | query_features | Execute CQL queries on vector data | | update_features | Modify feature attributes | | delete_features | Remove features based on criteria |

🛠️ Visualization

| Tool | Description | | -------------- | ------------------------------- | | generate_map | Create styled map images | | create_style | Define new SLD styles | | apply_style | Apply existing styles to layers |

🛠️ 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

📞 Support

For support, please Open an issue

🏆 Badges