Cumulocity

You can run a Python-based MCP Server to expose Cumulocity IoT platform capabilities via the MCP interface. It enables seamless interaction with device management, measurements, alarms, and dynamic data transformations, so you can integrate and automate workflows against your Cumulocity tenant.

How to use

Use an MCP client to connect to the server and perform operations such as listing devices, retrieving device details, querying measurements, monitoring active alarms, and evaluating dynamic expressions on device data. You can run the server locally for development or deploy it as a Cumulocity microservice for production integration. The standard flow is to start the MCP server and configure your client to point at its MCP endpoint, then perform the available operations listed in the tools.

How to install

Prerequisites you need before installation and running the MCP Server:

• Python 3.8+ or compatible environment
• pip (for Python package installation)
• optional: Docker and zip if you plan to build a microservice deployment package

Local installation options you can choose from:

# Install the MCP server package from PyPI
pip install mcp-server-c8y

# Run the server directly as a module
python -m mcp_server_c8y

Additional setup for deployment and usage

If you prefer to run the server via a microservice deployment package, you can build a deployment package that includes a Docker image and the necessary configuration files.

To build the microservice deployment package, run the provided build script. This script builds the Docker image, saves it as image.tar, and packages image.tar with cumulocity.json into a zip file for deployment.

./scripts/buildcontainer.sh

Usage with Claude Desktop

You can enable Claude Desktop to interact with your Cumulocity MCP server. Configure Claude Desktop to start the MCP server using uvx and pass the required environment variables for your Cumulicity instance.

"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>"
    }
  }
}

Cursor MCP Server settings

If you are configuring Cursor to connect to your MCP server, you can specify the MCP endpoint URL and authorization headers. The example shows how to point Cursor to the server’s MCP URL and supply a base64-encoded authorization token.

{
  "mcpServers": {
    "Cumulocity": {
      "url": "https://your-cumulocity-instance.com/service/mcp-server-c8y/mcp/",
      "headers": {
        "Authorization": "Basic <YOUR_BASE64_AUTH_TOKEN>"
      }
    }
  }
}

Available tools

Get Devices

List and filter devices with optional type and name filters and pagination parameters.

Get Device by ID

Retrieve detailed information for a specific device using its ID.

Get Child Devices

Query child devices for a given parent device.

Get Device Fragments

Access device fragments and their values for a device.

Get Device Measurements

Fetch device measurements with optional date range and page size filtering.

Get Active Alarms

Query currently active alarms with optional severity filter and pagination.

evaluate_jsonata_expression

Evaluate a JSONata expression against a provided JSON object.