Gotify MCP

🚀 Gotify MCP 服務器

本服務器提供了使用模型上下文協議（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）。

根據 Gotify 的 API 要求，create_message 工具特別需要一個 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="備份完成", message="服務器備份已成功完成。", priority=5)]

將 "YourAppTokenHere" 替換為你 Gotify 服務器中的實際應用程序令牌。

2. 獲取最近的消息

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

3. 創建新應用程序

[tool call: gotify-mcp.create_application(name="我的新警報應用", description="從我的腳本發送關鍵警報")]

(這將使用服務器上配置的 GOTIFY_CLIENT_TOKEN。)

4. 列出所有應用程序

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

5. 獲取服務器健康狀態

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

🐞 故障排除

• “GOTIFY_API_URL must be set” 錯誤：確保 GOTIFY_API_URL 已在你的 .env 文件中正確設置，並且服務器腳本正在加載它。
• 來自 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 實現說明

• 服務器使用 httpx 對 Gotify API 進行異步 HTTP 請求。
• 一個共享的 _request 輔助函數處理常見的請求邏輯，包括身份驗證和錯誤解析。
• 日誌配置為輸出到控制檯。如果需要，可以在腳本中啟用文件日誌記錄。
• 使用 python-dotenv 加載環境變量。
• 服務器使用 FastMCP 的 SSE 傳輸運行。 # gotify-mcp