Cumulocity MCP Server

Accede a la plataforma Cumulocity IoT para gestionar dispositivos, mediciones y alarmas.

GitHub
8
Prueba este MCPPatrocinado

Documentación

Cumulocity MCP Server

Un servidor basado en Python que proporciona funcionalidad de la plataforma Cumulocity IoT a través de la interfaz MCP (Model Control Protocol). Este servidor permite una interacción fluida con la gestión de dispositivos, mediciones y sistemas de alarmas de Cumulocity.

Herramientas Disponibles

Gestión de Dispositivos

  1. Obtener Dispositivos

    • Listar y filtrar dispositivos
    • Parámetros:
      • type: Filtrar por tipo de dispositivo
      • name: Filtrar por nombre de dispositivo
      • page_size: Resultados por página (máximo 2000)
      • current_page: Número de página

  2. Obtener Dispositivo por ID

    • Recuperar información detallada de un dispositivo específico
    • Parámetro:
      • device_id: Identificador del dispositivo

  3. Obtener Dispositivos Hijos

    • Ver los dispositivos hijos de un dispositivo específico
    • Parámetro:
      • device_id: Identificador del dispositivo padre

  4. Obtener Fragmentos de Dispositivo

    • Acceder a los fragmentos del dispositivo y sus valores
    • Parámetro:
      • device_id: Identificador del dispositivo

Mediciones

Obtener Mediciones de Dispositivo

  • Recuperar mediciones del dispositivo con filtrado por tiempo
  • Parámetros:
    • device_id: Identificador del dispositivo
    • date_from: Fecha de inicio (formato ISO 8601)
    • date_to: Fecha de fin (formato ISO 8601)
    • page_size: Número de mediciones a recuperar

Alarmas

Obtener Alarmas Activas

  • Monitorear alarmas activas en el sistema
  • Parámetros:
    • severity: Filtrar por nivel de severidad
    • page_size: Número de resultados a recuperar

Mapeador Dinámico

evaluate_jsonata_expression Evalúa una expresión JSONata contra un objeto JSON dado.

Entrada: Un objeto JSON como cadena y una cadena de expresión JSONata. Salida: Resultado de la evaluación de la expresión JSONata.

Instalación y Despliegue

Instalación Local

Usando uv (recomendado)

Cuando se usa uv no se necesita instalación específica para este paquete. Usaremos uvx para ejecutar directamente mcp-server-c8y.

Usando PIP

Alternativamente, puedes instalar mcp-server-c8y mediante pip:

pip install mcp-server-c8y

Después de la instalación, puedes ejecutarlo como un script usando:

python -m mcp_server_c8y

Despliegue en un Tenant de Cumulocity

Puedes desplegar este servidor como un microservicio de Cumulocity para una integración directa con tu tenant. Esto se hace subiendo un paquete de despliegue especial (mcp-server-c8y.zip) a tu tenant de Cumulocity.

Construcción del Paquete de Despliegue del Microservicio

  1. Asegúrate de tener Docker y zip instalados en tu sistema.
  2. Ejecuta el script de construcción proporcionado para crear el paquete de despliegue:
./scripts/buildcontainer.sh

Esto hará lo siguiente:

  • Construirá la imagen Docker para el microservicio
  • Guardará la imagen como image.tar en el directorio docker/
  • Empaquetará image.tar y cumulocity.json en docker/mcp-server-c8y.zip

Despliegue en Cumulocity

  1. Inicia sesión en tu tenant de Cumulocity como usuario con permisos de despliegue de microservicios.
  2. Navega a Administración > Ecosistema > Microservicios.
  3. Haz clic en Añadir microservicio y sube el archivo mcp-server-c8y.zip desde el directorio docker/.
  4. Espera a que el microservicio se despliegue e inicie. Deberías ver su estado como "Disponible" una vez que esté listo.
  5. El microservicio será accesible bajo la URL de servicio de tu tenant, típicamente: https://<your-tenant>.cumulocity.com/service/mcp-server-c8y/mcp/

Para más detalles sobre el despliegue de microservicios en Cumulocity, consulta la documentación oficial.

Uso con Claude Desktop

Este MCP Server se puede usar con Claude Desktop para permitir que Claude interactúe con tu plataforma Cumulocity IoT. Sigue estos pasos para configurarlo:

  1. Descarga e instala Claude Desktop

  2. Configura Claude Desktop para usar este MCP Server:

    • Abre Claude Desktop
    • Haz clic en el menú de Claude y selecciona "Settings..."
    • Navega a "Developer" en la barra izquierda
    • Haz clic en "Edit Config"

  3. Añade la siguiente configuración a tu claude_desktop_config.json:

Usando uvx 
"mcpServers": {
  "mcp-c8y": {
    "command": "uvx",
    "args": [
      "mcp-server-c8y",
      "--transport",
      "stdio"
    ],
    "env": {
      "C8Y_BASEURL": "https://your-cumulocity-instance.com",
      "C8Y_TENANT": "your-tenant-id",
      "C8Y_USER": "<your-username>",
      "C8Y_PASSWORD": "<your-password>"
    }
  }
}

Reemplaza los siguientes marcadores con tus valores reales:

  • https://your-cumulocity-instance.com: La URL de tu instancia de Cumulocity
  • your-tenant-id: El ID de tu tenant de Cumulocity
  • your-username: Tu nombre de usuario de Cumulocity
  • your-password: Tu contraseña de Cumulocity

  1. Reinicia Claude Desktop

  2. Ahora deberías ver un icono de martillo en la esquina inferior derecha del cuadro de entrada. Haz clic en él para ver las herramientas de Cumulocity disponibles.

Para información más detallada sobre el uso de MCP Servers con Claude Desktop, visita la documentación oficial de MCP.

Ejemplo de Configuración de MCP Server en Cursor

Si estás usando Cursor y has desplegado tu MCP Server en un tenant de Cumulocity, puedes configurar la conexión de tu MCP server con un archivo .cursor/mcp.json. Ejemplo (con datos sensibles anonimizados):

{
  "mcpServers": {
    "Cumulocity": {
      "url": "https://your-cumulocity-instance.com/service/mcp-server-c8y/mcp/",
      "headers": {
        "Authorization": "Basic <YOUR_BASE64_AUTH_TOKEN>"
      }
    }
  }
}
  • https://your-cumulocity-instance.com: La URL de tu instancia de Cumulocity
  • Reemplaza <YOUR_BASE64_AUTH_TOKEN> con tus credenciales reales codificadas en Base64. Nunca subas credenciales reales al control de versiones.

Contribuciones

¡Damos la bienvenida a contribuciones de todos! Así es como puedes contribuir a este proyecto:

  1. Haz un fork del repositorio
  2. Crea una nueva rama para tu funcionalidad o corrección de errores
  3. Realiza tus cambios siguiendo estas mejores prácticas:
    • Escribe mensajes de commit claros y descriptivos
    • Sigue el estilo y las convenciones de código existentes
    • Añade pruebas para nuevas funcionalidades
    • Actualiza la documentación según sea necesario
    • Asegúrate de que todas las pruebas pasen
  4. Envía una solicitud de extracción (pull request)