Cumulocity MCP Server

Cumulocity MCP 服务

一个基于 Python 的服务器，通过 MCP（Model Control Protocol）接口提供 Cumulocity IoT 平台功能。此服务器可无缝使用 Cumulocity 的设备管理、测量数据和告警系统。

可用工具

设备管理

1. 获取设备

   • 列出设备并进行筛选
   • 参数：
     • type：按设备类型筛选
     • name：按设备名称筛选
     • page_size：每页结果数（最多 2000）
     • current_page：页码

2. 按 ID 获取设备

   • 获取特定设备的详细信息
   • 参数：
     • device_id：设备标识符

3. 获取子设备

   • 查看特定设备的子设备
   • 参数：
     • device_id：父设备标识符

4. 获取设备片段

   • 访问设备片段及其值
   • 参数：
     • device_id：设备标识符

测量数据

获取设备测量数据

• 按时间筛选并获取设备测量数据
• 参数：
  • device_id：设备标识符
  • date_from：开始日期（ISO 8601 格式）
  • date_to：结束日期（ISO 8601 格式）
  • page_size：要获取的测量数据数量

告警

获取活动告警

• 监控系统中的活动告警
• 参数：
  • severity：按严重程度筛选
  • page_size：要获取的结果数量

动态映射器

evaluate_jsonata_expression 对给定的 JSON 对象执行 JSONata 表达式。

输入：一个以字符串表示的 JSON 对象和一个 JSONata 表达式字符串。 输出：JSONata 表达式的求值结果。

安装与部署

本地安装

使用 uv（推荐）

使用 uv 时，无需专门安装此软件包。我们将 使用 uvx 直接运行 mcp-server-c8y。

使用 PIP

也可以通过 pip 安装 mcp-server-c8y：

pip install mcp-server-c8y

安装后，可以将其作为脚本运行：

python -m mcp_server_c8y

在 Cumulocity 租户上部署

你可以将此服务器部署为 Cumulocity 微服务，以便直接集成到租户中。具体做法是将专用部署包（mcp-server-c8y.zip）上传到 Cumulocity 租户。

构建微服务部署包

1. 确保系统已安装 Docker 和 zip。
2. 运行提供的构建脚本以创建部署包：

./scripts/buildcontainer.sh

此操作将：

• 构建微服务的 Docker 镜像
• 将镜像保存为 docker/ 目录中的 image.tar
• 将 image.tar 和 cumulocity.json 打包到 docker/mcp-server-c8y.zip

部署到 Cumulocity

1. 使用具有微服务部署权限的用户登录 Cumulocity 租户。
2. 前往 Administration > Ecosystem > Microservices。
3. 点击 Add microservice，并上传 docker/ 目录中的 mcp-server-c8y.zip 文件。
4. 等待微服务部署并启动。准备就绪后，其状态应显示为“Available”。
5. 你可以通过租户的服务 URL 访问该微服务，通常为： https://<your-tenant>.cumulocity.com/service/mcp-server-c8y/mcp/

有关 Cumulocity 微服务部署的更多详情，请参阅官方文档。

在 Claude Desktop 中使用

此 MCP 服务可与 Claude Desktop 配合使用，让 Claude 与您的 Cumulocity IoT 平台交互。请按以下步骤进行设置：

1. 下载并安装 Claude Desktop

2. 配置 Claude Desktop 以使用此 MCP 服务：

   • 打开 Claude Desktop
   • 点击 Claude 菜单并选择“Settings...”
   • 在左侧栏中打开“Developer”
   • 点击“Edit Config”

3. 将以下配置添加到您的 claude_desktop_config.json 中：

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

将以下占位符替换为实际值：

• https://your-cumulocity-instance.com：您的 Cumulocity 实例 URL
• your-tenant-id：您的 Cumulocity 租户 ID
• your-username：您的 Cumulocity 用户名
• your-password：您的 Cumulocity 密码

4. 重启 Claude Desktop

5. 现在，您应该会在输入框右下角看到一个锤子图标。点击它即可查看可用的 Cumulocity 工具。

如需详细了解如何将 MCP 服务与 Claude Desktop 配合使用，请访问 MCP 官方文档。

Cursor MCP 服务设置示例

如果您正在使用 Cursor，并已将 MCP 服务部署到 Cumulocity 租户，可以通过 .cursor/mcp.json 文件配置 MCP 服务连接。示例（已匿名化敏感数据）：

{
  "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：您的 Cumulocity 实例 URL
• 将 <YOUR_BASE64_AUTH_TOKEN> 替换为实际的 Base64 编码凭据。切勿将真实凭据提交到版本控制系统。

参与贡献

欢迎所有人参与贡献！以下是为此项目做出贡献的方式：

1. Fork 此仓库
2. 为您的功能或错误修复创建一个新分支
3. 按照以下最佳实践进行修改：
   • 编写清晰、描述准确的提交消息
   • 遵循现有的代码风格和约定
   • 为新功能添加测试
   • 按需更新文档
   • 确保所有测试均通过
4. 提交拉取请求