Cumulocity MCP Server

Cumulocity MCP サーバー

MCP（Model Control Protocol）インターフェースを通じて、Cumulocity IoT プラットフォームの機能を提供する Python ベースのサーバーです。このサーバーにより、Cumulocity のデバイス管理、計測値、アラームシステムをシームレスに操作できます。

利用可能なツール

デバイス管理

1. デバイスの取得

   • デバイスの一覧表示と絞り込み
   • パラメーター：
     • type：デバイスの種類で絞り込み
     • name：デバイス名で絞り込み
     • page_size：1 ページあたりの結果数（最大 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（通常は次の URL）からアクセスできます。 https://<your-tenant>.cumulocity.com/service/mcp-server-c8y/mcp/

Cumulocity マイクロサービスのデプロイについて詳しくは、公式ドキュメントをご覧ください。

Claude Desktop での使用方法

この MCP サーバーは Claude Desktop と連携して、Claude が Cumulocity IoT プラットフォームとやり取りできるようにします。以下の手順で設定してください。

1. Claude Desktop をダウンロードしてインストールします。

2. この MCP サーバーを使用するように Claude Desktop を設定します。

   • 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 ツールを確認できます。

Claude Desktop で MCP サーバーを使用する方法の詳細については、公式 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. リポジトリをフォークします。
2. 機能追加またはバグ修正用の新しいブランチを作成します。
3. 次のベストプラクティスに従って変更を加えます。
   • 明確で説明的なコミットメッセージを記述します。
   • 既存のコードスタイルと規約に従います。
   • 新機能のテストを追加します。
   • 必要に応じてドキュメントを更新します。
   • すべてのテストが成功することを確認します。
4. プルリクエストを送信します。