Uptime Kuma MCP Server

Uptime Kuma MCP Server

このプロジェクトは、Uptime Kuma インスタンスとやり取りするための仲介役となる FastMCP（Message Control Protocol）サーバーを提供します。Uptime Kuma のモニターやタグ、ステータスページを管理するツール一式を公開し、ハートビートデータを取得できます。

機能

サーバーは次のツールを公開します。

• Uptime Kuma へのログイン：（内部関数。すべてのツールで使用）
• add_monitors：Uptime Kuma に複数の HTTP モニターを追加します。
• get_monitors：すべてのモニターの一覧を取得します。
• delete_monitors：ID を指定してモニターを削除します。
• pause_monitor：指定したモニターを一時停止します。
• resume_monitor：指定したモニターを再開します。
• get_monitor_beats：指定したモニターのハートビートを取得します。
• edit_monitor：既存のモニターの属性を編集します。
• add_monitor_tag：指定したモニターにタグを追加します。
• delete_monitor_tag：指定したモニターからタグを削除します。
• get_status_page：指定したステータスページの詳細を取得します。
• get_heartbeats：期間を指定し、ページネーションを使用して、指定したモニターのハートビートを取得します。
• get_tags：Uptime Kuma で定義されているすべてのタグを取得します。

動作の仕組み

1. FastMCP サーバー： アプリケーションの中核は FastMCP サーバーインスタンスです。このサーバーは、あらかじめ定義された「ツール」を実行するためのリクエストを待ち受けます。
2. Uptime Kuma API との連携： 各ツールは呼び出されると、まず uptime-kuma-api Python クライアントライブラリを使用して、設定済みの Uptime Kuma インスタンスへのログインを試みます。
3. 非同期操作： サーバーは、ノンブロッキング I/O を実現するために asyncio を使用して構築されています。uptime-kuma-api ライブラリは同期型のため、サーバーのイベントループがブロックされないよう、呼び出しを loop.run_in_executor でラップします。
4. 環境設定： Uptime Kuma の認証情報やサーバーのバインド情報など、重要な設定の詳細は環境変数で管理され、.env ファイルから読み込まれます。
5. ツールの定義： 公開される各機能（例：add_monitors、get_monitors）は、@mcp.tool() デコレーターを付けた非同期関数として定義されます。これらのツールは、Uptime Kuma API とやり取りするロジックを処理し、レスポンスを整形します。

前提条件

• Python 3.7 以降（asyncio.get_running_loop() が必要なため）
• Uptime Kuma インスタンス
• Uptime Kuma インスタンスへのアクセス認証情報（ユーザー名、パスワード）

セットアップ

1. リポジトリをクローンします（該当する場合）：

   git clone <repository_url>
   cd uptime-kuma-mcp-server
   

2. 依存関係をインストールします： 仮想環境の使用をおすすめします。

   python -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   

サーバーの実行

サーバーは次の 2 つのモードで実行できます。

1. STDIO モード（デフォルト）： このモードでは、標準入出力を使用して通信します。通常、別のアプリケーションがサブプロセスとしてサーバーを管理する場合に使用します。

   python main.py
   

   サーバーが起動し、その動作がコンソールに記録されます。

2. SSE（Server-Sent Events）モード： このモードでは、Server-Sent Events を使用して通信する HTTP サーバーを実行します。このモードで実行するには、main.py の if __name__ == "__main__": ブロックを変更し、main_stdio() の代わりに main_sse() を呼び出します。

   main.py の変更例：

   if __name__ == "__main__":
       # logger.info("Starting MCP server in STDIO mode as per __main__ block...")
       # main_stdio()
       # logger.info("MCP server (stdio mode) has finished or exited.")
   
       logger.info("Starting MCP server in SSE mode...")
       main_sse() # Call main_sse() here
       logger.info("MCP server (SSE mode) has finished or exited.")
   

   次に、以下を実行します。

   python main.py
   

   サーバーは、MCP_HOST と MCP_PORT の環境変数で指定されたホストとポートで待ち受けます（デフォルトは 0.0.0.0:8000 です）。

ツールの詳細

すべてのツールは、最初に Uptime Kuma へのログインを試みます。ログインに失敗すると、ツールの実行も失敗します。

add_monitors(urls: list[str])

• 説明： Uptime Kuma に複数の HTTP モニターを追加します。
• パラメーター：
  • urls（文字列のリスト）：モニターを作成する URL のリストです。モニター名は URL から生成されます。
• 戻り値： monitor_addition_results、kuma_url、total_requested、successfully_added を含む辞書です。

get_monitors()

• 説明： Uptime Kuma のすべてのモニターのリストを取得します。
• パラメーター： なし。
• 戻り値： monitors（項目数を絞ったリスト）、total_count、kuma_url を含む辞書です。

delete_monitors(ids: list[int])

• 説明： 指定した ID のモニターを削除します。
• パラメーター：
  • ids（整数のリスト）：削除するモニター ID のリストです。
• 戻り値： monitor_deletion_results、total_requested、successfully_deleted、kuma_url を含む辞書です。

pause_monitor(monitor_id: int)

• 説明： 特定のモニターを一時停止します。
• パラメーター：
  • monitor_id（整数）：一時停止するモニターの ID です。
• 戻り値： API のレスポンスとともに、成功または失敗を示す辞書です。

resume_monitor(monitor_id: int)

• 説明： 特定のモニターを再開します。
• パラメーター：
  • monitor_id（整数）：再開するモニターの ID です。
• 戻り値： API のレスポンスとともに、成功または失敗を示す辞書です。

get_monitor_beats(monitor_id: int, hours: int = 1)

• 説明： 指定した期間内の特定のモニターのハートビートを取得します。
• パラメーター：
  • monitor_id（整数）：モニターの ID です。
  • hours（整数、デフォルト：1）：取得するハートビートの期間を、現在から遡る時間数で指定します。
• 戻り値： beats、count、status を含む辞書です。

edit_monitor(monitor_id: int, options: dict)

• 説明： 既存のモニターを編集します。
• パラメーター：
  • monitor_id（整数）：編集するモニターの ID です。
  • options（辞書）：更新するモニター属性です（例：{"name": "New Name", "interval": 60}）。利用可能なフィールドについては、Uptime Kuma API を参照してください。
• 戻り値： API のレスポンスとともに、成功または失敗を示す辞書です。

add_monitor_tag(monitor_id: int, tag_id: int, value: str)

• 説明： 特定のモニターにタグを追加します。
• パラメーター：
  • monitor_id（整数）：モニターの ID です。
  • tag_id（整数）：追加するタグの ID です。
  • value（文字列）：タグの値です。
• 戻り値： API のレスポンスとともに、成功または失敗を示す辞書です。

delete_monitor_tag(monitor_id: int, tag_id: int)

• 説明： 特定のモニターからタグを削除します。
• パラメーター：
  • monitor_id（整数）：モニターの ID です。
  • tag_id（整数）：削除するタグの ID です。
• 戻り値： API のレスポンスとともに、成功または失敗を示す辞書です。

get_status_page(slug: str)

• 説明： スラッグで指定したステータスページの詳細を取得します。
• パラメーター：
  • slug（文字列）：ステータスページのスラッグです。
• 戻り値： ステータスページの data またはエラーメッセージを含む辞書です。

get_heartbeats(offset: int = 0, limit: int = 100)

• 説明： ページネーションを使用して、ハートビートのモニターデータを取得します。
  • 注：このツールは、まず Uptime Kuma からすべてのハートビートを取得してから、サーバー側でページネーションを適用します。非常に大きなデータセットでは、効率が悪い可能性があります。
• パラメーター：
  • offset（整数、デフォルト：0）：ページネーションのオフセットです。
  • limit（整数、デフォルト：100）：1 ページあたりのハートビート数の上限です。
• 戻り値： ページネーションされた data、total_available、count_returned、offset、limit を含む辞書です。

get_tags()

• 説明： Uptime Kuma で定義されているすべてのタグを取得します。
• パラメーター： なし。
• 戻り値： タグのリスト（data）とそのcountを含む辞書です。

ロギング

サーバーは Python のloggingモジュールを使用します。デフォルトでは、INFO レベルでログがコンソール（標準出力）に出力され、タイムスタンプ、ロガー名、ログレベル、メッセージが含まれます。

エラー処理

• 設定エラー： 必須の Uptime Kuma 環境変数（KUMA_URL、KUMA_USERNAME、KUMA_PASSWORD）が設定されていない場合、サーバーは起動に失敗し（ValueErrorが発生し）ます。
• API エラー： Uptime Kuma API とのやり取り中に発生したエラー（ログイン失敗、無効なモニター ID など）は記録されます。ツールは通常、「status」フィールドに「error」または「failed」を示し、「error_message」を含む辞書を返します。
• 一般的な例外： ツールハンドラー内で捕捉されなかった例外は記録された後、再送出されます。これにより、FastMCP フレームワークが適切に処理できます（クライアントへのエラーレスポンスの送信など）。