cumulocity

This MCP server provides an interface to Cumulocity IoT platform capabilities via MCP. It exposes device management endpoints (listing devices, fetching a device by ID, viewing child devices and device fragments), measurements retrieval for devices, active alarm monitoring, and a dynamic JSONata evaluation tool to transform or query JSON payloads. To use it, run the server (for example with Python: python -m mcp_server_c8y) and connect your MCP clients or Claude Desktop/Cumulocity integrations to the server's MCP endpoint. The available tools let you list and filter devices, retrieve specific device information, access related fragments, fetch measurements within date ranges, and filter active alarms by severity. The dynamic mapper lets you evaluate JSONata expressions against JSON inputs, enabling on-the-fly data shaping for downstream processing.

Prerequisites:

• Python 3.8+ installed on your system
• pip (Python package manager)
• Optional: uv/uvx if you prefer running the server with the uv runtime

Install via pip (recommended for Python-based deployment):

pip install mcp-server-c8y

Run the server directly as a module:

python -m mcp_server_c8y

Alternatively, using uv/uvx (recommended if you have uv installed):

uvx mcp-server-c8y --transport stdio

Configuration:

• Prepare the environment variables as shown in the mcp_config section (C8Y_BASEURL, C8Y_TENANT, C8Y_USER, C8Y_PASSWORD).
• You can also deploy the server in Docker or other environments if you package the Python app accordingly (see your deployment workflow).

Tips and common notes:

• Never commit real credentials in version control. Use environment-based configuration and secret management.
• The Cumulocity deployment flow described in the README includes packaging the microservice and deploying it to a Cumulocity tenant; ensure you have the proper permissions.
• When running locally, ensure the Cumulocity base URL, tenant, username, and password are correctly provided via env vars (C8Y_BASEURL, C8Y_TENANT, C8Y_USER, C8Y_PASSWORD).
• If you encounter connectivity or authentication issues, verify network access to the Cumulocity instance and double-check the tenant and credentials.
• The available tools require appropriate permissions on devices, measurements, and alarms in your Cumulocity tenant; ensure the service account has the necessary scopes.
• For Claude Desktop integration, configure the mcpServers entry using uvx or the Python runtime as shown in the README, and provide the correct base URL and credentials.