Pingera MCP Server

A Model Context Protocol (MCP) server for the Pingera monitoring service, providing seamless integration between AI models and monitoring data.

Features

Modular Architecture: Separate Pingera API client library with clean abstractions
Flexible Operation Modes: Run in read-only or read-write mode
MCP Tools: Execute monitoring operations through tools (list_pages, get_page_details, test_connection)
Robust Error Handling: Comprehensive error handling with custom exception hierarchy
Real-time Data: Direct integration with Pingera API v1 for live monitoring data
Type Safety: Pydantic models for data validation and serialization
Configurable: Environment-based configuration management

Quick Start

Prerequisites

Python 3.10+
UV package manager
Pingera API key - get one at app.pingera.ru

Installation and Setup

# Install dependencies
uv sync

# Set up your API key (required)
# Add PINGERA_API_KEY to your environment 

# Run the server
python -m pingera_mcp

The server will start in read-only mode by default and connect to the Pingera API.

Operation Modes

The Pingera MCP Server supports two transport modes:

1. Stdio Mode (Default)

Used for local integration with Claude Desktop and other stdio-based MCP clients. Authentication is configured via environment variables.

# Run in stdio mode (default)
python -m pingera_mcp

2. HTTP/SSE Mode

Enables web-based access through HTTP with Server-Sent Events. Perfect for remote clients, web applications, and programmatic access.

# Configure SSE mode
export PINGERA_TRANSPORT_MODE=sse
export PINGERA_HTTP_HOST=0.0.0.0
export PINGERA_HTTP_PORT=5000

# Run in SSE mode
python -m pingera_mcp

The server will be accessible at http://0.0.0.0:5000/mcp/

Authentication in SSE Mode

SSE mode supports two authentication methods via the Authorization header:

API Key Authentication (recommended for testing):
```
Authorization: YOUR_API_KEY
```
JWT Bearer Token Authentication:
```
Authorization: Bearer YOUR_JWT_TOKEN
```

Example: Python Client for SSE Mode

import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient

async def main():
    client = MultiServerMCPClient({
        "pingera": {
            "url": "http://0.0.0.0:5000/mcp/",
            "transport": "streamable_http",
            "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 Mode Configuration Options

PINGERA_TRANSPORT_MODE - Set to sse to enable HTTP/SSE mode (default: stdio)
PINGERA_HTTP_HOST - Host to bind to (default: 0.0.0.0)
PINGERA_HTTP_PORT - Port to listen on (default: 5000)
PINGERA_REQUIRE_AUTH_HEADER - Require Authorization header (default: false)

Note: In SSE mode, you can either:

Provide credentials via environment variables (PINGERA_API_KEY or PINGERA_JWT_TOKEN) as fallback
Send credentials in the Authorization header with each request (recommended)

When REQUIRE_AUTH_HEADER=true, the server will only accept requests with valid Authorization headers.

Claude Desktop Integration

To use this MCP server with Claude Desktop, you need to configure it in your Claude Desktop settings.

Installation

First, install the package globally using UV:

uv tool install pingera-mcp-server

Configuration

Open the Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

Add the following configuration:

{
  "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"
      }
    }
  }
}

Required Environment Variables

PINGERA_API_KEY - Your Pingera API key (required)

Optional Environment Variables

PINGERA_MODE - Operation mode: read_only (default) or read_write
PINGERA_BASE_URL - API endpoint (default: https://api.pingera.ru/v1)
PINGERA_TIMEOUT - Request timeout in seconds (default: 30)
PINGERA_MAX_RETRIES - Maximum retry attempts (default: 3)
PINGERA_DEBUG - Enable debug logging (default: false)
PINGERA_SERVER_NAME - Server display name (default: Pingera MCP Server)

Restart Claude Desktop

After updating the configuration file, restart Claude Desktop to load the new MCP server. You should now be able to access your Pingera monitoring data directly through Claude's interface.

Verify Installation

Once configured, you can ask Claude to:

"What are my status pages and their names?"
"Show details of a page with id ..."
"When was the last failed check for check ..."
"Run a simple synthetic check for the website with URL https://"

Configuration

Configure the server using environment variables:

# 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
PINGERA_TRANSPORT_MODE=stdio              # stdio (default) or sse

# SSE Mode Configuration (only used when TRANSPORT_MODE=sse)
PINGERA_HTTP_HOST=0.0.0.0                 # Host to bind to
PINGERA_HTTP_PORT=5000                     # Port to listen on
PINGERA_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 Tools

Available tools for AI agents:

Pages Management

list_pages - Get paginated list of monitored pages
- Parameters: page, per_page, status
get_page_details - Get detailed information about a specific page
- Parameters: page_id

Component Management

list_component_groups - List all component groups for monitoring organization
get_component_details - Get detailed information about a specific component
- Parameters: component_id

Monitoring Checks

list_checks - List all monitoring checks (HTTP, TCP, ping, etc.)
- Parameters: page, page_size, status, check_type
get_check_details - Get detailed information about a specific check
- Parameters: check_id

Alert Rules

list_alert_rules - List all alert rules and their trigger conditions

Heartbeat Monitoring

list_heartbeats - List all heartbeat monitors for cron jobs and scheduled tasks
- Parameters: page, page_size, status

Incident Management

list_incidents - List all incidents and their current status
- Parameters: page, page_size, status

Connection Testing

test_pingera_connection - Test API connectivity

Write Operations

Available only in read-write mode (PINGERA_MODE=read_write):

Pages Management

create_page - Create a new status page
- Parameters: name (required), subdomain, domain, url, language
update_page - Update existing status page configuration
- Parameters: page_id (required), name, subdomain, domain, url, language, additional kwargs
patch_page - Partially update specific page fields
- Parameters: page_id (required), kwargs for specific fields
delete_page - Permanently delete a status page
- Parameters: page_id (required)

Component Management

create_component - Create new component or component group
- Parameters: page_id (required), name (required), description, group, group_id, only_show_if_degraded, position, showcase, status
update_component - Update existing component configuration
- Parameters: page_id (required), component_id (required), name, description, group, group_id, only_show_if_degraded, position, showcase, status, additional kwargs
patch_component - Partially update specific component fields
- Parameters: page_id (required), component_id (required), kwargs for specific fields
delete_component - Delete a component permanently
- Parameters: page_id (required), component_id (required)

Monitoring Checks

create_check - Create new monitoring check
- Parameters: check_data (dict with check configuration)
update_check - Update existing monitoring check
- Parameters: check_id (required), check_data (dict with updated configuration)
delete_check - Delete monitoring check permanently
- Parameters: check_id (required)
pause_check - Temporarily pause monitoring check
- Parameters: check_id (required)
resume_check - Resume paused monitoring check
- Parameters: check_id (required)

Alert Rules

create_alert - Create new alert rule
- Parameters: alert_data (dict with alert configuration)
update_alert - Update existing alert rule
- Parameters: alert_id (required), alert_data (dict with updated configuration)
delete_alert - Delete alert rule permanently
- Parameters: alert_id (required)

Heartbeat Management

create_heartbeat - Create new heartbeat monitor
- Parameters: heartbeat_data (dict with heartbeat configuration)
update_heartbeat - Update existing heartbeat monitor
- Parameters: heartbeat_id (required), heartbeat_data (dict with updated configuration)
delete_heartbeat - Delete heartbeat monitor permanently
- Parameters: heartbeat_id (required)
send_heartbeat_ping - Manually send ping to heartbeat
- Parameters: heartbeat_id (required)

Incident Management

create_incident - Create new incident on status page
- Parameters: page_id (required), incident_data (dict with incident details)
update_incident - Update existing incident details
- Parameters: page_id (required), incident_id (required), incident_data (dict with updated details)
delete_incident - Delete incident permanently
- Parameters: page_id (required), incident_id (required)
add_incident_update - Add status update to incident
- Parameters: page_id (required), incident_id (required), update_data (dict with update details)
update_incident_update - Edit existing incident update
- Parameters: page_id (required), incident_id (required), update_id (required), update_data (dict with updated content)
delete_incident_update - Delete specific incident update
- Parameters: page_id (required), incident_id (required), update_id (required)

Access Control Modes

The server supports two levels of access control:

Read-Only Mode (Default)

Access monitoring data
View status pages and their configurations
Test API connectivity
No modification capabilities

Read-Write Mode

All read-only features
Create, update and delete resources: status pages, checks, alerts, heartbeats
Execute checks and get their results
Manage incidents and notifications

Set PINGERA_MODE=read_write to enable write operations.

Note: Access control mode is independent of transport mode. You can run the server in read-write mode with either stdio or SSE transport.

Architecture

Pingera API Client Library

Located in pingera/, this modular library provides:

PingeraClient: Main API client with authentication and error handling
Models: Pydantic data models for type-safe API responses
Exceptions: Custom exception hierarchy for error handling

MCP Server Implementation

FastMCP Framework: Modern MCP server implementation
Resource Management: Structured access to monitoring data
Tool Registration: Executable operations for AI agents
Configuration: Environment-based settings management

Testing

Running the Test Suite

Run all tests:

uv run pytest

Run tests with verbose output:

uv run pytest -v

Run specific test files:

uv run pytest tests/test_models.py
uv run pytest tests/test_config.py
uv run pytest tests/test_mcp_server.py

Run tests with coverage:

uv run pytest --cov=pingera --cov=config --cov=mcp_server

Test Structure

The test suite includes:

Unit Tests: Testing individual components (models, config, client)
Integration Tests: Testing MCP server functionality
Mock Tests: Testing with simulated API responses

Testing with MCP Inspector

The MCP Inspector is an official debugging tool that provides a web interface to test MCP servers interactively. It allows you to explore available resources, execute tools, and inspect the server's responses in real-time.

Setup Inspector

Create an mcp.json configuration file:

{
  "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"
      }
    }
  }
}

Run the inspector:

npx @modelcontextprotocol/inspector --config mcp.json

Open your browser to the provided URL (typically http://localhost:6274)

Using Inspector

The inspector provides:

Resources Tab: Browse available monitoring data resources
Tools Tab: Execute MCP tools like list_pages, get_page_details, etc.
Logs Tab: View detailed communication logs between the inspector and server
Interactive Testing: Test tool parameters and see real-time responses

This is the recommended way to test your MCP server integration before deploying with Claude Desktop or other MCP clients.

Manual Testing with `mcp_client.py`

mcp_client.py uses Gemini models and integrates with the MCP server to execute various tools. It is just an example and can be easly modified to use any other Large Language Model.

python mcp_client.py "Show me my status pages"

Error Handling

The system includes comprehensive error handling:

PingeraError: Base exception for all client errors
PingeraAPIError: API response errors with status codes
PingeraAuthError: Authentication failures
PingeraConnectionError: Network connectivity issues
PingeraTimeoutError: Request timeout handling

Name		Name	Last commit message	Last commit date
Latest commit History 287 Commits
build		build
docs		docs
pingera_mcp		pingera_mcp
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.replit		.replit
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
mcp_client.py		mcp_client.py
mcp_client_lg.py		mcp_client_lg.py
overview.md		overview.md
pyproject.toml		pyproject.toml
replit.md		replit.md
test_mcp_server.py		test_mcp_server.py
uv.lock		uv.lock

License

pingera/pingera-mcp

Folders and files

Latest commit

History

Repository files navigation

Pingera MCP Server

Features

Quick Start

Prerequisites

Installation and Setup

Operation Modes

1. Stdio Mode (Default)

2. HTTP/SSE Mode

Authentication in SSE Mode

Example: Python Client for SSE Mode

SSE Mode Configuration Options

Claude Desktop Integration

Installation

Configuration

Required Environment Variables

Optional Environment Variables

Restart Claude Desktop

Verify Installation

Configuration

MCP Tools

Pages Management

Component Management

Monitoring Checks

Alert Rules

Heartbeat Monitoring

Incident Management

Connection Testing

Write Operations

Pages Management

Component Management

Monitoring Checks

Alert Rules

Heartbeat Management

Incident Management

Access Control Modes

Read-Only Mode (Default)

Read-Write Mode

Architecture

Pingera API Client Library

MCP Server Implementation

Testing

Running the Test Suite

Test Structure

Testing with MCP Inspector

Setup Inspector

Using Inspector

Manual Testing with mcp_client.py

Error Handling

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Languages

Manual Testing with `mcp_client.py`