Cumulocity MCP Server

🚀 MCP Cumulocity Server

A Python-based server that provides Cumulocity IoT platform functionality through the MCP (Model Control Protocol) interface. This server supports seamless interaction with Cumulocity's device management, measurement, and alarm systems.

🚀 Quick Start

The MCP Cumulocity Server is a Python-based application that offers Cumulocity IoT platform functionality via the MCP interface. It enables seamless interaction with device management, measurement, and alarm systems.

✨ Features

Device Management

• List and filter devices.
• Retrieve detailed device information.
• View device hierarchies (sub-devices).
• Access device fragments and attributes.

Measurements

• Obtain device measurements with time filtering.
• View measurement history.

Alarms

• Monitor active alarms.
• Filter alarms by severity.
• Track alarm status.

📦 Installation

Prerequisites

• Python 3.13 or higher.
• Access to a Cumulocity IoT platform instance.
• Configuration of required environment variables.

Steps

1. Clone the repository:

git clone <repository-url>
cd mcp-c8y

2. Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On macOS/Linux
# Or
.venv\Scripts\activate  # On Windows

3. Install uv (if not already installed):

# On macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows PowerShell
irm https://astral.sh/uv/install.ps1 | iex

4. Install dependencies using uv:

uv install

5. Run the server:

uv run main:app

📚 Documentation

Configuration

Add the following content to the .env file in the project root directory to configure the Cumulocity service:

CUMULOCITY_API_KEY=your_api_key_here
CUMULOCITY_API_SECRET=your_api_secret_here
CUMULOCITY_BASE_URL=https://api.cumulocity.com

Integration with Claude Desktop

Follow these steps to integrate the MCP Cumulocity Server into Claude Desktop:

1. Install and run Claude Desktop.
2. Create a new project in Claude and specify the MCP Cumulocity Server as the data source.
3. Configure the project's environment variables, including the Cumulocity API key and secret.
4. Use Claude's workflow designer to integrate server functionality.

Available Tools

Device Management

• List devices.
• Get detailed information for a single device.
• Update device attributes.

Measurements

• Query historical measurement data.
• Add new measurements.
• Delete measurements within a specified time range.

Alarms

• Create new alarm rules.
• View active alarms.
• Manage alarm status.

📄 License

The use of the MCP Cumulocity Server is governed by the Apache License Version 2.0.

Unless required by applicable law or agreed to in writing, software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

🔧 Contribution Guidelines

We welcome contributions from everyone! Here's how you can contribute to this project:

1. Fork this repository.
2. Create a new branch for your feature or fix.
3. Make changes following these best practices:
   • Write clear and descriptive commit messages.
   • Follow the existing code style and conventions.
   • Add tests for new features.
   • Update documentation as needed.
   • Ensure all tests pass.
4. Submit a Pull Request.

Development Guidelines

• Use meaningful variable and function names.
• Add comments for complex logic.
• Write unit tests for new features.
• Keep commits focused and atomic.
• Follow the PEP 8 style guide.
• Use type hints for function parameters and return values.

Pull Request Process

1. Update README.md to reflect changes if necessary.
2. Update relevant documentation if there are functional changes.
3. A Pull Request will be merged after receiving approval from at least one maintainer.

For more detailed contribution guidelines, please refer to our [CONTRIBUTING.md] file.