Servidor MCP de GeoServer

Una implementación de servidor de Model Context Protocol (MCP) que conecta Modelos de Lenguaje de Gran Tamaño (LLMs) a la API REST de GeoServer, permitiendo que asistentes de IA interactúen con datos y servicios geoespaciales.

La versión 0.5.0 (Beta) está en desarrollo activo y se publicará próximamente. Estamos abiertos a contribuciones y damos la bienvenida a desarrolladores para que se unan a nosotros en la construcción de este proyecto.

🎥 Demostración

📋 Tabla de Contenidos

Características
Opciones de Despliegue
Requisitos Previos
Instalación
Almacenamiento de Archivos y Uso de --storage
Herramientas Disponibles
Desarrollo de Clientes
Características Planificadas
Contribuciones
Licencia
Proyectos Relacionados
Soporte
Insignias

🚀 Características

🔍 Consultar y manipular espacios de trabajo, capas y estilos de GeoServer
🗺️ Ejecutar consultas espaciales sobre datos vectoriales
🎨 Generar visualizaciones de mapas
🌐 Acceder a servicios web compatibles con OGC (WMS, WFS)
🛠️ Integración sencilla con clientes compatibles con MCP

🚀 Opciones de Despliegue

GeoServer MCP puede ejecutarse de dos maneras. Comparten la misma idea de producto (herramientas MCP sobre GeoServer) pero son artefactos separados. El paquete de Python no cambia.

                    GeoServer MCP
                         │
             ┌───────────┴───────────┐
             │                       │
      Python MCP Server       GeoServer Extension
             │                       │
             ▼                       ▼
        GeoServer                GeoServer
             │                       │
             └───────────┬───────────┘
                         │
                    MCP Interface
                         │
                         ▼
                     AI Agents

Servidor MCP de Python

Ejecute GeoServer MCP por separado (pip, Docker o Smithery). El proceso habla MCP con el agente y llama a la API REST de GeoServer. Esta es la implementación original, actualmente publicada.

Consulte Instalación a continuación.

Extensión de GeoServer

Instale la Extensión MCP de GeoServer directamente en GeoServer y exponga un endpoint MCP remoto en /geoserver/mcp. No se requiere un proceso auxiliar de Python. Está dirigida a GeoServer 2.28.x.

Consulte extension/README.md para arquitectura, instalación, configuración, seguridad y ejemplos de clientes.

📋 Requisitos Previos

Python 3.10 o superior
Instancia de GeoServer en ejecución con la API REST habilitada
Cliente compatible con MCP (como Claude Desktop o Cursor)
Conexión a Internet para la instalación de paquetes

🛠️ Instalación

Elija el método de instalación que mejor se adapte a sus necesidades:

Instalación mediante Smithery

Para instalar GeoServer MCP Server para Claude Desktop automáticamente mediante Smithery:

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

🛠️ Instalación (Docker)

La instalación con Docker es la forma más rápida y aislada de ejecutar el servidor MCP de GeoServer. Es ideal para:

Pruebas y evaluación rápidas
Despliegues en producción
Entornos donde desea evitar dependencias de Python
Despliegue consistente en diferentes sistemas

Ejecute geoserver-mcp:

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

Configure los clientes:

Si está usando Claude Desktop, edite claude_desktop_config.json Si está usando Cursor, cree .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"
      ]
    }
  }
}

🛠️ Instalación (pip)

La instalación con pip se recomienda para la mayoría de los usuarios que desean ejecutar el servidor directamente en su sistema. Este método es el mejor para:

Usuarios habituales que desean ejecutar el servidor localmente
Sistemas donde tiene Python 3.10+ instalado
Usuarios que desean personalizar la configuración del servidor
Propósitos de desarrollo y pruebas

Instale el administrador de paquetes uv.

pip install uv

Cree el Entorno Virtual (Python 3.10+):

Linux/Mac:

uv venv --python=3.10

Windows PowerShell:

uv venv --python=3.10

Instale el paquete usando pip:

uv pip install geoserver-mcp

Configure la conexión a GeoServer:

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"

Inicie el servidor:

Si va a usar Claude Desktop no necesita este paso. Para Cursor o su propio cliente personalizado debe ejecutar el siguiente código.

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 los Clientes:

Si está usando Claude Desktop, edite claude_desktop_config.json Si está usando Cursor, cree .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"
      ]
    }
  }
}

🛠️ Instalación para desarrollo

La instalación para desarrollo está diseñada para contribuyentes y desarrolladores que desean modificar el código base. Este método es adecuado para:

Desarrolladores que contribuyen al proyecto
Usuarios que necesitan modificar el código fuente
Probar nuevas características
Propósitos de depuración y desarrollo

Instale el administrador de paquetes uv.

pip install uv

Cree el Entorno Virtual (Python 3.10+):

uv venv --python=3.10

Instale el paquete usando pip:

uv pip install -e .

Configure la conexión a GeoServer:

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"

Inicie el servidor:

Si va a usar Claude Desktop no necesita este paso. Para Cursor o su propio cliente personalizado debe ejecutar el siguiente código.

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 los Clientes:

Si está usando Claude Desktop, edite claude_desktop_config.json Si está usando Cursor, cree .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"
      ]
    }
  }
}

Almacenamiento de Archivos y Uso de --storage

El servidor MCP de GeoServer admite un indicador opcional --storage para especificar un directorio base para todas las operaciones de lectura/escritura de archivos, como la carga de shapefiles, GeoTIFFs o la exportación de resultados.

Resumen

El indicador --storage establece la carpeta raíz para las operaciones de archivos de todas las herramientas relacionadas con datos.
Puede proporcionar rutas relativas (relativas a la raíz de almacenamiento) o rutas absolutas (ignorando la raíz de almacenamiento) como argumentos para las herramientas relevantes.
Si --storage no está configurado, las rutas se resuelven tal como las proporciona el usuario (relativas al directorio de trabajo o absolutas).

Ejemplo de CLI

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

Esto establece D:/my/data/dir como la ruta base para todos los archivos.

Ejemplo de llamada a herramienta en 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')

Las rutas absolutas (por ejemplo, 'C:/input/other.shp') siempre se usan tal cual.

Cuando se Ejecuta en Docker

Si usa Docker, asegúrese de que el directorio de almacenamiento esté montado como un volumen, por ejemplo:

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

Luego inicie el servidor con:

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

Mejores Prácticas

Use rutas relativas al interactuar con la API/herramientas, ya que mantiene su configuración portátil.
Para despliegues remotos o en contenedores, asegúrese siempre de que sus datos de archivos sean accesibles dentro del contenedor (use volúmenes de Docker si es necesario).
Consulte las cadenas de documentación de las herramientas para saber qué argumentos usan el sistema de almacenamiento.

El sistema --storage agiliza la gestión de archivos para todos los usuarios y hace que el despliegue sea mucho más flexible.

🛠️ Herramientas Disponibles

Esta sección detalla todas las herramientas y recursos disponibles expuestos por el servidor MCP de GeoServer. Estas herramientas permiten a los LLMs interactuar con la API REST de GeoServer para una gestión integral de datos geoespaciales.

🌍 Endpoints de Recursos

Los endpoints de recursos proporcionan acceso directo a los recursos de GeoServer mediante un patrón de URI.

URI de Recurso	Descripción
`geoserver://catalog/workspaces`	Listar espacios de trabajo disponibles
`geoserver://catalog/layers/{workspace}/{layer}`	Obtener información sobre una capa específica
`geoserver://services/wms/{request}`	Manejar solicitudes de recursos WMS
`geoserver://services/wfs/{request}`	Manejar solicitudes de recursos WFS

📦 Gestión de Espacios de Trabajo

Herramienta	Descripción
`list_workspaces`	Listar espacios de trabajo disponibles en GeoServer
`create_workspace`	Crear un nuevo espacio de trabajo en GeoServer

📁 Gestión de Almacenes de Datos y Coberturas

Herramienta	Descripción
`create_datastore`	Crear un nuevo almacén de datos en el espacio de trabajo dado
`create_featurestore`	Crear un nuevo almacén de entidades en el espacio de trabajo dado
`create_gpkg_datastore`	Crear un almacén de datos GeoPackage (GPKG)
`create_shp_datastore`	Crear un almacén de datos ESRI Shapefile
`create_coveragestore`	Crear un nuevo almacén de coberturas en un espacio de trabajo
`delete_coveragestore`	Eliminar un almacén de coberturas de un espacio de trabajo
`get_coveragestore`	Obtener detalles sobre un único almacén de coberturas
`get_coveragestores`	Obtener todos los almacenes de coberturas de un espacio de trabajo
`get_datastore`	Obtener un almacén de datos específico por nombre
`get_datastores`	Listar todos los almacenes de datos en el espacio de trabajo dado

🗺️ Gestión de Capas

Herramienta	Descripción
`get_layer_info`	Obtener información detallada sobre una capa
`list_layers`	Listar capas en GeoServer, opcionalmente filtradas por espacio de trabajo
`create_layer`	Crear una nueva capa en GeoServer
`delete_resource`	Eliminar un recurso de GeoServer (genérico)

🧩 Gestión de Grupos de Capas

Herramienta	Descripción
`create_layergroup`	Crear un nuevo grupo de capas con capas específicas y (opcionalmente) estilos
`get_layergroup`	Obtener un grupo de capas de un espacio de trabajo
`get_layergroups`	Listar todos los grupos de capas en un espacio de trabajo
`add_layer_to_layergroup`	Añadir una capa específica a un grupo de capas
`remove_layer_from_layergroup`	Eliminar una capa de un grupo
`delete_layergroup`	Eliminar un grupo de capas de un espacio de trabajo
`update_layergroup`	Actualizar los detalles y la configuración de un grupo de capas

👥 Gestión de Usuarios y Grupos de Usuarios

Herramienta	Descripción
`create_user`	Crear un nuevo usuario para la seguridad de GeoServer
`delete_user`	Eliminar un usuario por nombre
`get_all_users`	Listar todos los usuarios en la instancia de GeoServer
`modify_user`	Modificar las propiedades de un usuario existente
`create_usergroup`	Crear un nuevo grupo de usuarios
`delete_usergroup`	Eliminar un grupo de usuarios
`get_all_usergroups`	Devolver todos los grupos de usuarios

📊 Gestión de Tipos de Entidad y Atributos

Herramienta	Descripción
`query_features`	Consultar características de una capa vectorial usando filtro CQL
`publish_featurestore`	Publicar un featurestore existente
`publish_featurestore_sqlview`	Publicar un featurestore usando una definición de vista SQL
`edit_featuretype`	Editar la configuración de un tipo de característica en un store
`get_featuretypes`	Listar todos los tipos de características en un store dado
`get_feature_attribute`	Obtener el esquema/detalles de atributos de una característica

🎨 Gestión de Estilos

Herramienta	Descripción
`create_style`	Crear un nuevo estilo SLD en GeoServer
`publish_style`	Asignar/publicar un estilo a una capa
`create_catagorized_featurestyle`	Crear un estilo categorizado para características
`create_classified_featurestyle`	Crear un estilo clasificado para características
`create_coveragestyle`	Crear un estilo de cobertura ráster
`create_outline_featurestyle`	Crear un estilo simple solo de contorno para características

⚙️ Operaciones de Sistema y Servicios

Herramienta	Descripción
`get_manifest`	Obtener metadatos/detalles del manifiesto de GeoServer
`get_status`	Obtener el estado general del servidor
`get_system_status`	Obtener resumen/estado del sistema desde GeoServer
`get_version`	Obtener la cadena de versión de GeoServer
`reload_geoserver`	Recargar el catálogo y la configuración desde el disco
`reset_geoserver`	Restablecer todas las cachés/conexiones de GeoServer
`update_service`	Actualizar opciones seleccionadas del servicio OGC
`publish_time_dimension_to_coveragestore`	Agregar o actualizar una dimensión de tiempo para un store de cobertura (para series temporales)

📝 Utilidades XML de Estilos

Herramienta	Descripción
`style_catagorize_xml`	Generar SLD para estilo vectorial categorizado
`style_classified_xml`	Obtener XML SLD para estilo vectorial clasificado
`style_coverage_style_colormapentry`	Generar entradas de mapa de colores para SLD ráster
`style_coverage_style_xml`	Generar XML para SLD ráster/cobertura
`style_outline_only_xml`	XML para estilo solo de contorno para una geometría

🛠️ Desarrollo de Clientes

Si planeas desarrollar tu propio cliente para interactuar con el servidor GeoServer MCP, puedes encontrar inspiración en la implementación de cliente de ejemplo en examples/client.py. Este ejemplo demuestra:

Cómo establecer una conexión con el servidor MCP
Cómo enviar solicitudes y manejar respuestas
Manejo básico de errores y gestión de conexiones
Uso de ejemplo de varias herramientas y operaciones

El cliente de ejemplo sirve como un buen punto de partida para entender el protocolo e implementar tus propias aplicaciones cliente.

Además, aquí está el uso de ejemplo:

Listar Workspaces


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

Obtener Información de Capa


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

Consultar Características


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

Generar Mapa


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

🔮 Características Planificadas

Gestión de datos de cobertura y ráster
Seguridad y control de acceso
Capacidades avanzadas de estilo
Operaciones de procesamiento WPS
Integración con GeoWebCache

🤝 Contribuciones

¡Damos la bienvenida a las contribuciones! Así es como puedes ayudar:

Haz un fork del repositorio
Crea una rama de características (git checkout -b feature/AmazingFeature)
Confirma tus cambios (git commit -m 'Add some AmazingFeature')
Empuja a la rama (git push origin feature/AmazingFeature)
Abre una Pull Request

Asegúrate de que la descripción de tu PR describa claramente el problema y la solución. Incluye el número de issue relevante si corresponde.

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

🔗 Proyectos Relacionados

Model Context Protocol - La implementación principal de MCP
GeoServer REST API - Documentación oficial de REST de GeoServer
GeoServer REST Python Client - Cliente Python para la API REST de GeoServer

🌐 Ver También: GIS MCP

Para una automatización más amplia de datos geoespaciales y aún más características MCP relacionadas con GIS, consulta GIS MCP by mahdin75.

📞 Soporte

Para soporte, abre un issue

GeoServer MCP Server

Documentación