GeoServer MCP Server
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
- 🔍 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:
🛠️ 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.
- Create the Virtual Environment (Python 3.10+):
Linux/Mac:
Windows PowerShell:
- 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
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
- 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.
- Create the Virtual Environment (Python 3.10+):
- Install the package using pip:
- 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
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
- 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"
]
}
}
}
🛠️ 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"]
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
🤝 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.
📞 Support
For support, please Open an issue
🏆 Badges