Gotify MCP

🚀 Gotify MCP Server

このサーバーは、Model Context Protocol (MCP) を使用してGotifyインスタンスとやり取りするツールを提供します。FastMCPを使用して構築されており、メッセージの送信、アプリケーションやクライアントの管理、ヘルスチェックやバージョン情報の取得などが可能です。

このサーバーは、共同設計フェーズで承認されたツールセットを実装しています。

✨ 主な機能

設計の理由

これらのツールは、Gotifyのコア機能を網羅するために選ばれました。ユーザーは以下のことができます。

• 通知を送信する (create_message)。
• メッセージを取得および管理する (get_messages, delete_message)。
• メッセージを送信するアプリケーションを管理する (create_application, get_applications, update_application, delete_application)。
• メッセージを受信するクライアントを管理する (create_client, get_clients)。
• Gotifyサーバーを監視する (get_health, get_version)。

create_message ツールは、Gotifyのメッセージ送信APIの要件に従い、app_token パラメーターが必要です。その他の管理ツールは、グローバルに設定された GOTIFY_CLIENT_TOKEN を使用します。

実装されたツール

• create_message(app_token: str, message: str, title: Optional[str], priority: Optional[int], extras: Optional[Dict]): 新しいメッセージを送信します。
• get_messages(limit: Optional[int], since: Optional[int]): メッセージを取得します。
• delete_message(message_id: int): 特定のメッセージを削除します。
• delete_all_messages(): すべてのメッセージを削除します。
• create_application(name: str, description: Optional[str], default_priority: Optional[int]): アプリケーションを作成します。
• get_applications(): すべてのアプリケーションを取得します。
• update_application(app_id: int, name: Optional[str], description: Optional[str], default_priority: Optional[int]): アプリケーションを更新します。
• delete_application(app_id: int): アプリケーションを削除します。
• create_client(name: str): クライアントを作成します。
• get_clients(): すべてのクライアントを取得します。
• get_health(): Gotifyサーバーのヘルスチェックを行います。
• get_version(): Gotifyサーバーのバージョンを取得します。

実装されたリソース

• gotify://application/{app_id}/messages?limit={limit}&since_id={since_id}: 特定のアプリケーションのメッセージを一覧表示します。
• gotify://currentuser: 現在認証されているユーザーの詳細を提供します（GOTIFY_CLIENT_TOKEN を使用）。

📦 インストール

前提条件

• Python 3.8以上
• 稼働中のGotifyサーバーインスタンス

インストール手順

1. サーバーファイルをクローンまたはダウンロードする： gotify_mcp_server.py、requirements.txt、.env.example をディレクトリ（例: gotify-mcp）に配置します。
2. サーバーディレクトリに移動する：

   cd path/to/gotify-mcp
   

3. 仮想環境を作成する（推奨）：

   python -m venv .venv
   source .venv/bin/activate  # Windowsの場合: .venv\Scripts\activate
   

4. 依存関係をインストールする：

   pip install -r requirements.txt
   

5. 環境変数を設定する： サンプル環境ファイルをコピーします。

   cp .env.example .env
   

   .env ファイルを編集して、Gotifyサーバーの詳細を設定します。

   GOTIFY_API_URL="YOUR_GOTIFY_SERVER_URL" # 例: http://localhost:80 または https://gotify.example.com
   GOTIFY_CLIENT_TOKEN="YOUR_GOTIFY_ADMIN_CLIENT_TOKEN" # アプリケーション/メッセージを管理する権限を持つクライアントトークン
   
   # オプション: HTTPサーバー設定
   # GOTIFY_MCP_TRANSPORT="http" # トランスポートタイプ: 'http', 'sse', または 'stdio' (デフォルト: http)
   # GOTIFY_MCP_HOST="0.0.0.0" # MCP HTTPサーバーがリッスンするホスト
   # GOTIFY_MCP_PORT="8000"    # MCP HTTPサーバーのポート
   
   # オプション: ロギング設定
   # LOG_LEVEL="INFO" # DEBUG, INFO, WARNING, ERROR, CRITICAL のいずれか
   

   • GOTIFY_API_URL: Gotifyサーバーの完全なベースURL。
   • GOTIFY_CLIENT_TOKEN: Gotifyサーバーのクライアントトークン。すべてのツールを使用する場合は、アプリケーション、クライアント、およびメッセージを管理する権限を持つ必要があります。create_message の場合は、app_token を直接ツールに渡します。

サーバーの起動

Pythonスクリプトを実行します。

python gotify_mcp_server.py

デフォルトでは、サーバーは http://0.0.0.0:8000/mcp でHTTPサービスを開始します。 サーバーが起動したことを示すログ出力が表示されます。

📚 ドキュメント

クライアント設定

このサーバーはデフォルトでHTTP（ストリーミング可能）トランスポートを使用して実行されます。HTTPトランスポートをサポートする任意のMCPクライアント（例: Clineや fastmcp-client を使用したカスタムスクリプト）で接続できます。トランスポートは GOTIFY_MCP_TRANSPORT 環境変数で 'http'、'sse'、または 'stdio' を使用するように設定できます。

Cline設定の例 (cline_mcp_settings.json)： Clineがインストールされ、設定されていることを確認します。cline_mcp_settings.json ファイル（通常は ~/.cline/ または ~/.config/cline/ にあります）に以下を追加します。

{
  "mcpServers": {
    "gotify-mcp": {
      "url": "http://localhost:8000/mcp", // ホスト/ポートが異なる場合は調整する
      "disabled": false,
      "autoApprove": [], // オプション: 自動承認するツールのリスト
      "timeout": 30 // オプション: リクエストのタイムアウト時間（秒）
    }
    // ... 他のサーバー
  }
}

• MCPサーバーが localhost:8000 以外のホストまたはポートで実行されている場合は、url フィールドを適宜更新してください。
• 設定を追加した後、Clineを（再）起動します。Gotify MCPツールが使用可能になります。

💻 使用例

MCPクライアント（例: Cline）がサーバーに接続されていると仮定します。

基本的な使用法

1. メッセージを送信する：

[tool call: gotify-mcp.create_message(app_token="YourAppTokenHere", title="Backup Complete", message="Server backup finished successfully.", priority=5)]

"YourAppTokenHere" をGotifyサーバーの実際のアプリケーショントークンに置き換えてください。

2. 最近のメッセージを取得する：

[tool call: gotify-mcp.get_messages(limit=10)]

3. 新しいアプリケーションを作成する：

[tool call: gotify-mcp.create_application(name="My New Alerting App", description="Sends critical alerts from my script")]

（これはサーバーに設定された GOTIFY_CLIENT_TOKEN を使用します。）

4. すべてのアプリケーションを一覧表示する：

[tool call: gotify-mcp.get_applications()]

5. サーバーのヘルスチェックを行う：

[tool call: gotify-mcp.get_health()]

🔧 技術詳細

トラブルシューティング

• "GOTIFY_API_URL must be set" エラー： .env ファイルで GOTIFY_API_URL が正しく設定されていること、およびサーバースクリプトがそれを読み込んでいることを確認します。
• Gotifyからの認証エラー（例: 401 Unauthorized）：
  • create_message の場合: ツールに渡す app_token が有効でアクティブであることを確認します。
  • その他のツールの場合: .env ファイルの GOTIFY_CLIENT_TOKEN がGotifyサーバーで十分な権限を持つ有効なクライアントトークンであることを確認します。
• MCPサーバーへの接続問題：
  • gotify_mcp_server.py スクリプトが実行されていることを確認します。
  • ファイアウォールが GOTIFY_MCP_HOST および GOTIFY_MCP_PORT（デフォルト 0.0.0.0:8000）をブロックしていないことを確認します。
  • MCPクライアント設定のURLがサーバーがリッスンしているアドレスと一致していることを確認します。
• ツール実行エラー： サーバーログ（gotify_mcp_server.py のコンソール出力）を確認して、MCPサーバーまたはGotify API自体からの詳細なエラーメッセージを確認します。

FastMCP実装の注意事項

• サーバーは、Gotify APIへの非同期HTTPリクエストに httpx を使用しています。
• 共通のリクエストロジック（認証やエラー解析を含む）は、共有された _request ヘルパー関数で処理されます。
• ロギングはコンソールに出力するように設定されています。必要に応じて、スクリプト内でファイルロギングを有効にすることができます。
• 環境変数は python-dotenv を使用して読み込まれます。
• サーバーはFastMCPのSSEトランスポートを使用して実行されます。 # gotify-mcp