关于 Pingera Mcp
Pingera MCP Server 将 Pingera 监控数据和操作接入 AI 客户端，适合管理状态页、监控检查与事件的团队。支持只读或读写模式，并可通过 stdio 或 HTTP/SSE 连接。
主要功能
- 01查询状态页、组件和检查
- 02查看告警规则、心跳与事件
- 03创建和修改监控资源
- 04按模式控制读写权限
- 05支持 stdio 与 HTTP/SSE 传输
适用场景
- 01检查监控页面和检查状态
- 02追踪事件及告警规则
- 03创建或调整监控检查
- 04通过远程连接访问监控数据
MCP 相关
向 MCP 客户端提供 Pingera 监控查询和管理工具。可按只读或读写模式及 SSE 请求头筛选可用工具。
配置
本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。
暂未收录安装方式
我们还没有获取到这个服务的安装包或远程地址，请按项目 README 中的说明安装。
工具
还没有获取到工具列表
本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。
详细介绍
Pingera MCP 服务
一个用于 Pingera 监控服务 的模型上下文协议（MCP）服务，可实现 AI 模型与监控数据的无缝集成。
功能
- 模块化架构：独立的 Pingera API 客户端库，具有清晰的抽象层
- 灵活的运行模式：可在只读或读写模式下运行
- MCP 工具：通过工具执行监控操作（list_pages、get_page_details、test_connection）
- 健壮的错误处理：完善的错误处理机制和自定义异常层级
- 实时数据：直接集成 Pingera API v1，获取实时监控数据
- 类型安全：使用 Pydantic 模型进行数据验证和序列化
- 可配置：基于环境变量的配置管理
快速开始
前提条件
- Python 3.10+
- UV 包管理器
- Pingera API 密钥 - 在 app.pingera.ru 获取
安装和设置
# Install dependencies
uv sync
# Set up your API key (required)
# Add PINGERA_API_KEY to your environment
# Run the server
python -m pingera_mcp
服务默认以只读模式启动，并连接到 Pingera API。
运行模式
Pingera MCP 服务支持两种传输模式：
1. Stdio 模式（默认）
用于与 Claude Desktop 及其他基于 stdio 的 MCP 客户端进行本地集成。通过环境变量配置身份验证。
# Run in stdio mode (default)
python -m pingera_mcp
2. HTTP/SSE 模式
通过 HTTP 和服务器发送事件（Server-Sent Events）实现 Web 访问。非常适合远程客户端、Web 应用和程序化访问。
# Configure SSE mode
export TRANSPORT_MODE=sse
export HTTP_HOST=0.0.0.0
export HTTP_PORT=5000
# Run in SSE mode
python -m pingera_mcp
服务可通过 http://0.0.0.0:5000/sse 访问。
SSE 模式下的身份验证
SSE 模式支持通过 Authorization 标头使用两种身份验证方式：
-
API 密钥身份验证（推荐用于测试）：
Authorization: YOUR_API_KEY -
JWT Bearer 令牌身份验证：
Authorization: Bearer YOUR_JWT_TOKEN
选择性开放工具
在 SSE 模式下，可以使用 X-MCP-Tools 标头控制向客户端开放哪些工具。这适用于将 AI Agent 的操作限制为特定操作，或创建不同的访问级别。
示例：仅开放只读页面工具：
client = MultiServerMCPClient({
"pingera": {
"url": "http://0.0.0.0:5000/sse",
"transport": "sse",
"headers": {
"Authorization": "YOUR_API_KEY",
"X-MCP-Tools": "list_pages,get_page_details,list_component_groups"
}
}
})
X-MCP-Tools 标头接受以逗号分隔的工具名称列表。客户端只能使用指定的工具。如果省略此标头，则可使用与当前服务模式（只读或读写）兼容的所有工具。
注意：工具筛选会遵循服务的运行模式。即使通过标头请求，读写操作工具在只读模式下也不会开放。
示例：SSE 模式的 Python 客户端
import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient
async def main():
client = MultiServerMCPClient({
"pingera": {
"url": "http://0.0.0.0:5000/sse",
"transport": "sse",
"headers": {
"Authorization": "YOUR_API_KEY", # or "Bearer YOUR_JWT_TOKEN"
}
}
})
# Get available tools
tools = await client.get_tools()
print(f"Available tools: {len(tools)}")
asyncio.run(main())
SSE 模式配置选项
TRANSPORT_MODE- 设置为sse以启用 HTTP/SSE 模式（默认值：stdio）HTTP_HOST- 要绑定的主机（默认值：0.0.0.0）HTTP_PORT- 监听端口（默认值：5000）REQUIRE_AUTH_HEADER- 是否要求提供 Authorization 标头（默认值：false）
注意：在 SSE 模式下，你可以：
- 通过环境变量（PINGERA_API_KEY 或 PINGERA_JWT_TOKEN）提供凭据作为备用方案
- 在每个请求的 Authorization 标头中发送凭据（推荐）
当 REQUIRE_AUTH_HEADER=true 时，服务只接受带有有效 Authorization 标头的请求。
Claude Desktop 集成
要将此 MCP 服务与 Claude Desktop 配合使用，需要在 Claude Desktop 设置中进行配置。
安装
首先，使用 UV 全局安装软件包：
uv tool install pingera-mcp-server
配置
打开 Claude Desktop 配置文件：
- macOS：
~/Library/Application Support/Claude/claude_desktop_config.json - Windows：
%APPDATA%/Claude/claude_desktop_config.json
添加以下配置：
{
"mcpServers": {
"pingera": {
"command": "uv",
"args": [
"run",
"--with",
"pingera-mcp-server",
"--python",
"3.10",
"python",
"-m",
"pingera_mcp"
],
"env": {
"PINGERA_API_KEY": "your_api_key_here",
"PINGERA_MODE": "read_only",
"PINGERA_BASE_URL": "https://api.pingera.ru/v1",
"PINGERA_TIMEOUT": "30",
"PINGERA_MAX_RETRIES": "3",
"PINGERA_DEBUG": "false",
"PINGERA_SERVER_NAME": "Pingera MCP Server"
}
}
}
}
必需的环境变量
PINGERA_API_KEY- 你的 Pingera API 密钥（必需）
可选环境变量
PINGERA_MODE- 操作模式：read_only（默认）或read_writePINGERA_BASE_URL- API 端点（默认：https://api.pingera.ru/v1）PINGERA_TIMEOUT- 请求超时时间（秒）（默认：30）PINGERA_MAX_RETRIES- 最大重试次数（默认：3）PINGERA_DEBUG- 启用调试日志（默认：false）PINGERA_SERVER_NAME- 服务显示名称（默认：Pingera MCP Server）
重启 Claude Desktop
更新配置文件后，请重启 Claude Desktop 以加载新的 MCP 服务。现在，你应该可以直接通过 Claude 的界面访问 Pingera 监控数据。
验证安装
配置完成后，你可以询问 Claude：
- “有哪些状态页面？它们的名称是什么？”
- “显示 ID 为……的页面详情。”
- “检查……上一次检查失败是什么时候？”
- “对 URL 为 https:// 的网站运行一次简单的合成检查。”
配置
使用环境变量配置服务：
# Required (for stdio mode or as fallback in SSE mode)
PINGERA_API_KEY=your_api_key_here
# OR
PINGERA_JWT_TOKEN=your_jwt_token_here
# Transport Mode
TRANSPORT_MODE=stdio # stdio (default) or sse
# SSE Mode Configuration (only used when TRANSPORT_MODE=sse)
HTTP_HOST=0.0.0.0 # Host to bind to
HTTP_PORT=5000 # Port to listen on
REQUIRE_AUTH_HEADER=false # Require Authorization header
# Optional
PINGERA_MODE=read_only # read_only or read_write
PINGERA_BASE_URL=https://api.pingera.ru/v1
PINGERA_TIMEOUT=30
PINGERA_MAX_RETRIES=3
PINGERA_DEBUG=false
PINGERA_SERVER_NAME=Pingera MCP Server
MCP 工具
供 AI Agent 使用的工具：
页面管理
list_pages- 获取分页的受监控页面列表- 参数：
page、per_page、status
- 参数：
get_page_details- 获取特定页面的详细信息- 参数：
page_id
- 参数：
组件管理
list_component_groups- 列出监控组织的所有组件组get_component_details- 获取特定组件的详细信息- 参数：
component_id
- 参数：
监控检查
list_checks- 列出所有监控检查（HTTP、TCP、ping 等）- 参数：
page、page_size、status、check_type
- 参数：
get_check_details- 获取特定检查的详细信息- 参数：
check_id
- 参数：
告警规则
list_alert_rules- 列出所有告警规则及其触发条件
心跳监控
list_heartbeats- 列出所有用于 cron 作业和计划任务的心跳监控器- 参数：
page、page_size、status
- 参数：
事件管理
list_incidents- 列出所有事件及其当前状态- 参数：
page、page_size、status
- 参数：
连接测试
test_pingera_connection- 测试 API 连通性
写入操作
仅在读写模式（PINGERA_MODE=read_write）下可用：
页面管理
create_page- 创建新的状态页面- 参数：
name（必填）、subdomain、domain、url、language
- 参数：
update_page- 更新现有状态页面配置- 参数：
page_id（必填）、name、subdomain、domain、url、language、其他 kwargs
- 参数：
patch_page- 部分更新指定页面字段- 参数：
page_id（必填）、针对特定字段的 kwargs
- 参数：
delete_page- 永久删除状态页面- 参数：
page_id（必填）
- 参数：
组件管理
create_component- 创建新组件或组件组- 参数：
page_id（必填）、name（必填）、description、group、group_id、only_show_if_degraded、position、showcase、status
- 参数：
update_component- 更新现有组件配置- 参数：
page_id（必填）、component_id（必填）、name、description、group、group_id、only_show_if_degraded、position、showcase、status、其他 kwargs
- 参数：
patch_component- 部分更新指定组件字段- 参数：
page_id（必填）、component_id（必填）、针对特定字段的 kwargs
- 参数：
delete_component- 永久删除组件- 参数：
page_id（必填）、component_id（必填）
- 参数：
监控检查
create_check- 创建新的监控检查- 参数：
check_data（包含检查配置的字典）
- 参数：
update_check- 更新现有监控检查- 参数：
check_id（必填）、check_data（包含更新后配置的字典）
- 参数：
delete_check- 永久删除监控检查- 参数：
check_id（必填）
- 参数：
pause_check- 暂停监控检查- 参数：
check_id（必填）
- 参数：
resume_check- 恢复已暂停的监控检查- 参数：
check_id（必填）
- 参数：
告警规则
create_alert- 创建新的告警规则- 参数：
alert_data（包含告警配置的字典）
- 参数：
update_alert- 更新现有告警规则- 参数：
alert_id（必填）、alert_data（包含更新后配置的字典）
- 参数：
delete_alert- 永久删除告警规则- 参数：
alert_id（必填）
- 参数：
心跳管理
create_heartbeat- 创建新的心跳监控器- 参数：
heartbeat_data（包含心跳配置的字典）
- 参数：
update_heartbeat- 更新现有心跳监控器- 参数：
heartbeat_id（必填）、heartbeat_data（包含更新后配置的字典）
- 参数：
delete_heartbeat- 永久删除心跳监控器- 参数：
heartbeat_id（必填）
- 参数：
send_heartbeat_ping- 手动向心跳监控器发送 ping- 参数：
heartbeat_id（必填）
- 参数：
事件管理
create_incident- 在状态页上创建新事件- 参数：
page_id（必填）、incident_data（包含事件详情的字典）
- 参数：
update_incident- 更新现有事件详情- 参数：
page_id（必填）、incident_id（必填）、incident_data（包含更新后详情的字典）
- 参数：
delete_incident- 永久删除事件- 参数：
page_id（必填）、incident_id（必填）
- 参数：
add_incident_update- 为事件添加状态更新- 参数：
page_id（必填）、incident_id（必填）、update_data（包含更新详情的字典）
- 参数：
update_incident_update- 编辑现有事件更新- 参数：
page_id（必填）、incident_id（必填）、update_id（必填）、update_data（包含更新后内容的字典）
- 参数：
delete_incident_update- 删除特定事件更新- 参数：
page_id（必填）、incident_id（必填）、update_id（必填）
- 参数：
访问控制模式
服务支持两个级别的访问控制：
只读模式（默认）
- 访问监控数据
- 查看状态页及其配置
- 测试 API 连通性
- 不具备修改功能
读写模式
- 包含所有只读功能
- 创建、更新和删除资源：状态页、检查、告警、心跳
- 执行检查并获取结果
- 管理事件和通知
设置 PINGERA_MODE=read_write 以启用写操作。
注意：访问控制模式独立于传输模式。你可以通过 stdio 或 SSE 传输，在读写模式下运行服务。
架构
Pingera API 客户端库
此模块化库位于 pingera/，提供：
- PingeraClient：主 API 客户端，具备身份验证和错误处理功能
- Models：用于实现类型安全 API 响应的 Pydantic 数据模型
- Exceptions：用于错误处理的自定义异常体系
MCP 服务实现
- FastMCP Framework：现代 MCP 服务实现
- Resource Management：对监控数据的结构化访问
- Tool Registration：供 AI Agent 使用的可执行操作
- Configuration：基于环境的设置管理
测试
运行测试套件
运行所有测试：
uv run pytest
以详细输出运行测试：
uv run pytest -v
运行指定测试文件：
uv run pytest tests/test_models.py
uv run pytest tests/test_config.py
uv run pytest tests/test_mcp_server.py
运行测试并生成覆盖率报告：
uv run pytest --cov=pingera --cov=config --cov=mcp_server
测试结构
测试套件包括：
- 单元测试：测试各个组件（模型、配置、客户端）
- 集成测试：测试 MCP 服务的功能
- 模拟测试：使用模拟的 API 响应进行测试
使用 MCP Inspector 测试
MCP Inspector 是一款官方调试工具，提供用于交互式测试 MCP 服务的 Web 界面。它允许你探索可用资源、执行工具，并实时检查服务的响应。
设置 Inspector
- 创建
mcp.json配置文件：
{
"mcpServers": {
"pingera": {
"command": "uv",
"args": [
"run",
"--with",
"pingera-mcp-server",
"--python",
"3.10",
"python",
"-m",
"pingera_mcp"
],
"env": {
"PINGERA_API_KEY": "your_pingera_api_key",
"PINGERA_MODE": "read_only",
"PINGERA_BASE_URL": "https://api.pingera.ru/v1",
"PINGERA_TIMEOUT": "30",
"PINGERA_MAX_RETRIES": "3",
"PINGERA_DEBUG": "false"
}
}
}
}
- 运行 Inspector：
npx @modelcontextprotocol/inspector --config mcp.json
- 在浏览器中打开提供的 URL（通常为
http://localhost:6274）
使用 Inspector
Inspector 提供：
- Resources 选项卡：浏览可用的监控数据资源
- Tools 选项卡：执行 MCP 工具，例如
list_pages、get_page_details等。 - Logs 选项卡：查看 Inspector 与服务之间的详细通信日志
- 交互式测试：测试工具参数并查看实时响应
建议在使用 Claude Desktop 或其他 MCP 客户端部署之前，通过这种方式测试 MCP 服务集成。
使用 mcp_client.py 手动测试
mcp_client.py 使用 Gemini 模型，并与 MCP 服务集成以执行各种工具。它仅为示例，可轻松修改为使用其他任何大模型。
python mcp_client.py "Show me my status pages"
错误处理
系统包含全面的错误处理：
PingeraError：所有客户端错误的基础异常PingeraAPIError：包含状态码的 API 响应错误PingeraAuthError：身份验证失败PingeraConnectionError：网络连接问题PingeraTimeoutError：请求超时处理
评论
支持 Markdown
一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。