JinDaGe - gotify-mcp MCP Details

article

README

🚀 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 服务器实例。

安装

克隆或下载服务器文件：将 gotify_mcp_server.py、requirements.txt 和 .env.example 放置在一个目录中（例如 gotify-mcp）。
导航到服务器目录：

cd path/to/gotify-mcp

创建虚拟环境（推荐）：

python -m venv .venv
source .venv/bin/activate  # 在 Windows 上使用：.venv\Scripts\activate

安装依赖项：

pip install -r requirements.txt

设置环境变量：复制示例环境文件：

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

gotify-mcp