chaplin-health-mcp 0.1.0

MCP server for querying and analyzing AWS Health Events through AI-powered natural language queries

Chaplin Health Events MCP Server

MCP server for AWS Health Event analysis — AI-powered diagnostics, critical event tracking, and proactive health intelligence across your AWS accounts.

Powered by Chaplin — an agentic AI platform that transforms how organizations understand and respond to AWS health events through natural language queries and real-time analysis.

Features

Health Event Intelligence

• Event category breakdown: Issue, Account Notification, Scheduled Change, Investigation — with event and service counts
• Event type classification: Configuration Alerts, Cost Impact Events, Maintenance Updates, Migration Requirements, Operational Notifications, Security Compliance
• Critical event tracking: Upcoming events in 30-day and 30–60 day windows, plus past due events (120 days)
• Drill-down details: Filter events by service, category, status, region, account, event type, or ARN

AI-Powered Analysis

• Natural language queries: Ask questions about your health events in plain English
• Agentic diagnostics: Same Strands Agent + Bedrock Claude pipeline that powers the Chaplin web dashboard
• Contextual insights: Impact analysis combining event data with account metadata

Dashboard Parity

Every feature on the Chaplin web dashboard is available as an MCP tool — no browser required.

Prerequisites

1. AWS Account with appropriate permissions
2. AWS CLI configured with credentials
3. Amazon Bedrock: Access to Claude Sonnet 4 in us-east-1
4. DynamoDB: chaplin-health-events table populated with health event data (see Chaplin setup)
5. Python: 3.10 or higher

Installation

Kiro	Cursor	VS Code

⚡ Quick Install (script)

cd mcp/
chmod +x install.sh
./install.sh

This creates a virtual environment, installs dependencies, and configures the MCP server in ~/.kiro/settings/mcp.json.

🐳 Using Docker

Build the image from the repo root:

docker build -t chaplin-health-mcp-server -f mcp/Dockerfile .

Configure your MCP client:

{
  "mcpServers": {
    "chaplin-health": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "--interactive",
        "-v", "~/.aws:/home/app/.aws:ro",
        "--env", "FASTMCP_LOG_LEVEL=ERROR",
        "--env", "AWS_REGION=us-east-1",
        "--env", "AWS_PROFILE=default",
        "chaplin-health-mcp-server:latest"
      ],
      "env": {},
      "disabled": false,
      "autoApprove": []
    }
  }
}

Note: The container mounts ~/.aws as read-only for credentials. Change AWS_PROFILE to use a different profile.

🔧 Manual Configuration

Add to ~/.kiro/settings/mcp.json (Kiro CLI) or your MCP client's config:

For Linux/macOS:

{
  "mcpServers": {
    "chaplin-health": {
      "command": "/path/to/mcp/venv/bin/python3",
      "args": ["/path/to/mcp/mcp_server.py"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

Tools

Overview & Summary (instant, no LLM cost)

Tool	Description
get_health_summary	High-level counts by service, status, category, region
get_critical_events_count	Count of critical events in the next 30 days
get_event_categories	Event Categories — Issue, Account Notification, Scheduled Change, Investigation
get_event_type_stats	Event Types — Configuration Alerts, Cost Impact, Maintenance, Migration, Operational, Security

Detail Views (instant, no LLM cost)

Tool	Description
get_event_category_details(category_id)	Events for a specific category (e.g. issue, accountNotification)
get_event_type_details(event_type_id)	Events for a specific type (e.g. migration-requirements, security-compliance)
get_drill_down_details(...)	Filter events by service, category, status, region, account, event_type, arn
get_cached_prompts	Previously used prompts with usage counts (Suggested Prompts sidebar)

AI Agent Analysis (30–60s, uses Bedrock Claude)

Tool	Description
analyze_health_events(prompt)	Free-form natural language analysis — same as AI Agents Diagnostics UI
get_critical_events_30d	Upcoming critical events in next 30 days — same as dashboard red card
get_critical_events_60d	Upcoming critical events in 30–60 day window
get_past_due_events	Past due events (120 days) still open/upcoming

Example Prompts

# Quick data (instant)
Give me a summary of all health events
Show me the event categories breakdown
What are the event type stats?

# AI analysis (30-60s)
What Bedrock models are going end of life?
Give me open Lambda events and highlight critical ones
Can you check upcoming events for RDS?
Show me critical events in the next 30 days
Which accounts have the most open health events?

AWS Authentication

The MCP server requires AWS credentials with the following permissions:

• dynamodb:Scan, dynamodb:Query, dynamodb:DescribeTable on chaplin-health-events table
• bedrock:InvokeModel for Claude Sonnet 4 in us-east-1 (required for AI analysis tools only)

Configuration

Environment Variable	Description	Default
AWS_REGION	AWS region for DynamoDB and Bedrock	us-east-1
AWS_PROFILE	AWS profile from ~/.aws/credentials	default
FASTMCP_LOG_LEVEL	MCP server log level	ERROR

Architecture

MCP Client (Kiro/Cursor/VS Code)
    │
    ▼ (JSON-RPC over stdio)
┌─────────────────────────────┐
│   mcp_server.py (FastMCP)   │
│                             │
│  Summary tools ──► DynamoDB │  (instant, no LLM)
│                             │
│  AI tools ──► Strands Agent │  (30-60s, Bedrock Claude)
│              ──► DynamoDB   │
│              ──► Bedrock    │
└─────────────────────────────┘

The MCP server reuses the same agent pipeline as the Chaplin web dashboard — agentic_analysis_simple.py → DBQueryBuilder.py → DynamoDB + Bedrock Claude. Results are identical.