A
licenseA
qualityD
maintenanceMCP server for running infrastructure health checks with TIBET provenance. It enables users to define, execute, and audit process health checks with dependency chaining and drift tracking.
6
MIT
AWS Health MCP Server
Officialby aws-samples
Inspect AWS Health information account- and organization-wide through read-only MCP tools.
View current/active AWS service health events and affected resources for open events.
Query health events for a specific AWS service, or get completed/closed events with optional service filtering.
List scheduled maintenance and upcoming changes.
Check organization-wide health events, org service health, affected entities, service-specific events, per-account events, and org scheduled changes.
All tools are read-only; mutating AWS Health API operations are not exposed.
Provides tools to retrieve AWS Health events, affected entities, and service status for your AWS account.
Provides tools to retrieve AWS Health events and affected entities across all accounts in your AWS Organization.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@AWS Health MCP Server What's happening with EC2 right now?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
AWS Health MCP Server
Disclaimer: This AWS content is provided subject to the terms of the AWS Customer Agreement available at https://aws.amazon.com/agreement or other written agreement between the Customer and Amazon Web Services. This is sample code for demonstration purposes only. It is not intended for production use. You should work with your security and legal teams to meet your organizational security, regulatory, and compliance requirements before any deployment.
MCP server that exposes AWS Health API as tools. Works with Claude Desktop, Kiro or any MCP-compatible client.
📖 Blog: Building an AWS Health MCP Server for Agentic Operations
Prerequisites
Python 3.10+
AWS credentials configured (
aws configureor environment variables)AWS Business or Enterprise Support plan (required for Health API)
For org-level tools: AWS Organizations with Health service access enabled
Related MCP server: AWS Pricing Calculator MCP Server
Setup
Add this to your MCP config file:
Claude Desktop:
~/Library/Application Support/Claude/claude_desktop_config.jsonKiro:
~/.kiro/settings/mcp.jsonAmazon Q CLI:
~/.aws/amazonq/mcp.json
Using uvx from PyPI (recommended)
{
"mcpServers": {
"aws-health": {
"command": "uvx",
"args": ["aws-health-mcp-server"],
"env": {
"AWS_PROFILE": "default"
}
}
}
}Using pip
pip install aws-health-mcp-serverFrom a local clone
{
"mcpServers": {
"aws-health": {
"command": "uv",
"args": ["run", "--directory", "/path/to/aws-health-mcp-server", "aws-health-mcp-server"],
"env": {
"AWS_PROFILE": "default"
}
}
}
}That's it. uv handles the venv and dependencies automatically.
Tools
All tools are read-only and annotated as such. The Health API's two mutating
operations (EnableHealthServiceAccessForOrganization and
DisableHealthServiceAccessForOrganization) are deliberately not exposed.
Start here
Tool | Description |
| Event counts by service, status, category or region. Cheap overview — the listing tools include full descriptions and can be very large. |
| Full detail for specific events, by ARN |
| Which events affect your resources, e.g. |
| Diagnose credentials, support plan and org access |
Account-Level
Tool | Description |
| All active health events |
| Resources impacted by open events |
| Events for a specific service (e.g., EC2, RDS) |
| Recently resolved events |
| Upcoming maintenance |
| How many resources an event hits, without listing them |
Organization-Level
Tool | Description |
| Events across all accounts |
| Active events org-wide |
| Impacted resources across accounts |
| Service-specific events org-wide |
| Events for a specific account |
| Org-wide scheduled maintenance |
| Accounts affected by one event |
Discovery
Tool | Description |
| Event types AWS Health reports, and the service codes it uses |
Example Prompts
"Are there any active AWS health events?"
"Give me a summary of current AWS issues by service"
"What's happening with EC2 right now?"
"What's broken in us-west-2?"
"Is instance i-1234567890abcdef0 affected by anything?"
"Show me scheduled maintenance across my organization"
"What resources are affected by current issues in account 123456789012?"
Service names
Pass service names however you like — EC2, ec2, Step Functions,
api gateway all resolve. The valid set comes from the Health API itself, so
every service AWS covers is reachable, and names are mapped to the codes AWS
actually uses (Step Functions is STATES, EventBridge is EVENTS). Use
list_event_types to browse them. Common names resolve in about a second; an
unrecognised name (a typo, say) triggers a one-time ~8 second load of the full
service list, which is then cached.
Environment Variables
Variable | Default | Description |
| none | AWS credentials profile |
|
| Logging level ( |
|
| API read timeout in seconds |
|
| Max concurrent Health API calls |
|
| Cache event descriptions and affected accounts |
|
| Cache lifetime in seconds |
|
| Cache lifetime for the service catalog |
The region is not configurable; see Regions and availability.
Regions and availability
The AWS Health API runs as an active-passive pair: us-east-1 (active) and
us-east-2 (passive), behind a single global endpoint,
global.health.amazonaws.com, whose DNS (10 second TTL) points at whichever
region is currently active.
Which endpoint this server uses. The client is created for
us-east-1, which boto3/botocore resolve tohttps://global.health.amazonaws.com. This holds for every botocore release this package supports (checked on 1.34.162 and 1.43.89). The server therefore follows AWS's DNS failover; there is no region setting because the global endpoint chooses for you.No client-side failover. The server does not detect a failover itself or retry against
us-east-2. Recovery relies on DNS re-resolution and botocore's retries (3 attempts, adaptive), so requests made during the switch can fail and a long-running server may need a call or two to pick up the new region. Restart the server if calls keep failing after AWS reports the Health API has failed over.Passive data can lag. AWS notes that only the active endpoint has the latest data; the passive endpoint is eventually consistent. During an incident, treat results as potentially slightly behind.
Not verified. Requests to the global endpoint are signed for
us-east-1(botocore's rule). AWS documents the signing region as that of the active endpoint, so it is not confirmed that requests signed forus-east-1are accepted after a failover tous-east-2. A real failover could not be tested. Callinghealth.us-east-2.amazonaws.comdirectly requires signing forus-east-2; aus-east-1signature is rejected withInvalidSignatureException.
Pinning the server to us-east-2 is not supported. Overriding the endpoint
alone (for example with AWS_ENDPOINT_URL_HEALTH) still signs requests for
us-east-1 and is rejected with InvalidSignatureException.
Errors and partial results
Failures are reported, never turned into an empty answer:
Tool errors (no Health access, API rejection, throttling that stops a request) are returned with the MCP
isErrorflag set, so clients and agents can tell a failure from a result.Partial results: when one lookup inside a larger answer fails (for example the affected accounts of a single event), the rest is still returned with a "Warning: partial results" footer naming what is missing.
Searches:
find_events_for_resourcesreturns an error rather than "no event affects it" if some events could not be checked.
Troubleshooting
"SubscriptionRequiredException" — You need AWS Business or Enterprise Support.
"AccessDeniedException" — Your IAM user/role needs health:Describe* permissions.
Org tools return access error — Enable Health service access from your management account:
aws health enable-health-service-access-for-organizationServer not starting — Check the MCP client logs. Common issues:
Wrong Python path in config (use the full
.venv/bin/pythonpath)Missing dependencies (run
pip install -e .in the venv)
Development
git clone https://github.com/aws-samples/sample-health-mcp-server.git
cd aws-health-mcp-server
uv sync --extra dev
uv run pytest tests/ -vLicense
MIT-0
Available Tools
18 toolscheck_health_accessARead-onlyIdempotent
Diagnose whether this server can actually reach the AWS Health API.
Reports the calling identity, whether the account's support plan allows Health API access, and whether organization view is enabled. Run this first when other tools return access errors.
Example prompts:
"Why can't you see my AWS health events?"
"Is AWS Health set up correctly?"
"Do I have organization-wide health access?"
Inputs: no named parameters. Returns: result
count_affected_entitiesARead-onlyIdempotent
Count the resources affected by events, without listing them.
Use this before the entity-listing tools when an event could touch thousands of resources.
Args: event_arns: One or more event ARNs.
Example prompts:
"How many instances does this retirement event affect?"
"What's the blast radius of these events?"
Inputs: event_arns (required). Returns: result
find_events_for_resourcesARead-onlyIdempotent
Find which health events affect specific resources of yours.
Answers "is my instance / cluster / database affected by anything?".
Matching goes through DescribeAffectedEntities, where entity values match exactly. The equivalent filter on DescribeEvents cannot be used for this: it also returns events that have no entities at all, so a resource ID that exists nowhere still comes back with matches.
Args: entity_values: Resource identifiers, e.g. ['i-1234567890abcdef0']. include_closed: Also search resolved events, not just open/upcoming.
Example prompts:
"Is i-1234567890abcdef0 affected by any AWS issue?"
"Do any current events touch my cluster my-prod-cluster?"
Inputs: entity_values (required), include_closed. Returns: result
get_affected_entitiesARead-onlyIdempotent
Get affected entities for all open AWS health events.
Shows resources impacted by active health events, grouped by event and status.
Example prompts:
"What resources are affected by current AWS issues?"
"Show me all impacted AWS entities"
"Which AWS resources are experiencing problems?"
Inputs: no named parameters. Returns: result
get_completed_eventsARead-onlyIdempotent
Get completed/closed health events.
Args: service: Optional. The AWS service name to filter by. Case insensitive. regions: Optional. Restrict to these AWS regions, e.g. ['us-west-2'].
Example prompts:
"Show me recently resolved AWS issues"
"What EC2 problems were fixed in us-east-1?"
"Get history of resolved incidents"
Inputs: regions, service. Returns: result
get_event_detailsARead-onlyIdempotent
Get the full detail of specific AWS health events by ARN.
Use this to drill into events surfaced by the listing tools, instead of pulling every description for every event.
Args: event_arns: One or more event ARNs, as returned by the listing tools.
Example prompts:
"Give me the full details of that EC2 retirement event"
"What exactly does event arn:aws:health:... say?"
Inputs: event_arns (required). Returns: result
get_org_account_eventsARead-onlyIdempotent
Get health events for a specific AWS account in your organization.
Args: account_id: The 12-digit AWS account ID. regions: Optional. Restrict to these AWS regions, e.g. ['us-west-2'].
Example prompts:
"What health events are affecting account 123456789012?"
"Show me all issues in my account"
Inputs: account_id (required), regions. Returns: result
get_org_affected_entitiesARead-onlyIdempotent
Get affected entities for AWS health events across your organization.
Args: account_id: Optional. The AWS account ID to filter events for. event_arn: Optional. The ARN of a specific event to get details for.
Example prompts:
"What resources are affected by current AWS issues across my organization?"
"Show me impacted entities in account 123456789012"
Inputs: event_arn, account_id. Returns: result
get_org_health_eventsARead-onlyIdempotent
Get health events across your AWS Organization.
If no arguments are provided, returns all active org health events.
Args: service: Optional. The AWS service name to filter by. Case insensitive. account_id: Optional. The AWS account ID to filter events for. status: Optional. 'active' (default) or 'closed'. regions: Optional. Restrict to these AWS regions, e.g. ['us-west-2'].
Example prompts:
"Show me org-wide AWS health events"
"What issues affect account 123456789012?"
"Any org-wide events in ap-southeast-2?"
Inputs: status, regions, service, account_id. Returns: result
get_org_scheduled_changesARead-onlyIdempotent
Get scheduled changes/maintenance events across your AWS Organization.
Returns upcoming maintenance affecting accounts in your organization.
Example prompts:
"What maintenance is planned across my organization?"
"Show me upcoming AWS changes affecting my accounts"
Inputs: no named parameters. Returns: result
get_org_service_eventsARead-onlyIdempotent
Get health events for a specific AWS service across your organization.
Args: service: The AWS service name (e.g., 'EC2', 'RDS', 'LAMBDA'). Case insensitive. regions: Optional. Restrict to these AWS regions, e.g. ['us-west-2'].
Example prompts:
"What's happening with EC2 across my organization?"
"Show me all RDS issues affecting my AWS accounts"
Inputs: service (required), regions. Returns: result
get_org_service_healthARead-onlyIdempotent
Get current AWS service health events across your organization.
Provides a comprehensive overview of active health events across all accounts in your AWS Organization.
Example prompts:
"Show me all current AWS service health issues across my organization"
"Are there any active AWS service disruptions affecting multiple accounts?"
Inputs: no named parameters. Returns: result
get_scheduled_changesARead-onlyIdempotent
Get all scheduled changes/maintenance events across AWS services.
Returns upcoming maintenance windows, planned updates, and infrastructure improvements.
Args: regions: Optional. Restrict to these AWS regions, e.g. ['us-west-2'].
Example prompts:
"What maintenance is planned for AWS services?"
"Any upcoming maintenance in eu-west-1?"
"When is the next AWS maintenance?"
Inputs: regions. Returns: result
get_service_eventsARead-onlyIdempotent
Get health events for a specific AWS service.
Args: service: The AWS service name (e.g., 'EC2', 'RDS', 'LAMBDA'). Case insensitive. Use list_event_types to discover the codes AWS Health uses. regions: Optional. Restrict to these AWS regions, e.g. ['us-west-2'].
Example prompts:
"What's happening with EC2 right now?"
"Any RDS issues in eu-west-1?"
"Are there any problems with S3?"
Inputs: service (required), regions. Returns: result
get_service_healthARead-onlyIdempotent
Get current AWS service health events.
Returns active and upcoming AWS health events with descriptions and timelines. Consider summarize_health_events first: this returns full descriptions and can be very large on a busy account.
Args: regions: Optional. Restrict to these AWS regions, e.g. ['us-west-2'].
Example prompts:
"Show me all current AWS service health issues"
"What's broken in us-west-2?"
"Are there any active AWS service disruptions?"
Inputs: regions. Returns: result
list_affected_accountsBRead-onlyIdempotent
List the organization accounts affected by a single health event.
Args: event_arn: The ARN of an organization health event.
Example prompts:
"Which accounts does this event affect?"
"How wide is the blast radius of this event across my organization?"
Inputs: event_arn (required). Returns: result
list_event_typesARead-onlyIdempotent
List the event types AWS Health can report, optionally for one service.
Also the way to discover valid service names: the service codes AWS Health uses do not always match the marketing name (Step Functions is 'STATES', EventBridge is 'EVENTS').
Args: service: Optional. Restrict to one AWS service. Case insensitive. category: Optional. One of 'issue', 'accountNotification', 'scheduledChange', 'investigation'.
Example prompts:
"What service names does AWS Health use?"
"What kinds of EC2 events can AWS Health report?"
Inputs: service, category. Returns: result
summarize_health_eventsARead-onlyIdempotent
Count active AWS health events without returning their descriptions.
A cheap overview for "is anything wrong?" questions. Listing tools return full descriptions and can run to tens of thousands of tokens; this returns counts only.
Args: group_by: One of 'service', 'status', 'category' or 'region'. include_closed: Include resolved events as well as open/upcoming ones.
Example prompts:
"How many AWS health events are open, by service?"
"Give me a summary of current AWS issues"
"Which regions have active events?"
Inputs: group_by, include_closed. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
A3.8/5.0
Scored across 18 tools
Disambiguation3/5
There are systematic org/non-org pairs (get_service_health vs get_org_service_health, get_affected_entities vs get_org_affected_entities, etc.) which are nameable-apart, but the fuzzy boundaries between get_service_health and get_service_events, and between the several overlapping event-listing tools, create real misselection risk.
Naming Consistency5/5
All names follow a consistent snake_case verb_noun pattern (get_, list_, count_, summarize_, find_, check_) with predictable prefixes for org-scoped variants.
Tool Count4/5
18 tools is at the upper end but justified by the read-only domain spanning single-account, org-wide, entity, and summary operations. It is slightly heavy but each tool earns a place.
Completeness4/5
The surface covers listing, drilling into details, affected entities, counts, summaries, event-type discovery, org-wide views, and an access diagnostic — strong lifecycle coverage for a read-only API. Minor gaps around pagination/continuation handling keep it from a 5.
Maintenance
ActivityNo data
ResponsivenessOutdated data
Related MCP Connectors
Hosted MCP server for AWS cloud spend: service breakdowns, anomalies, savings and forecasts.
Read-only MCP server for AIStatusDashboard status, incidents, metrics, and fallback recommendations.
Read-only health context MCP server for Iris users.
Manage uptime monitors, incidents and status pages from any MCP client.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server that provides tools for automating AWS Pricing Calculator estimate generation.MIT
- AlicenseNot gradedqualityDmaintenanceThis MCP server provides tools for inspecting AWS cloud infrastructure, including listing S3 buckets, EC2 instances, and fetching CloudWatch logs using your local AWS credentials.9 npmMIT
- FlicenseAqualityCmaintenanceA local MCP server for read-only querying of AWS resources (Lambda, S3) via Boto3, currently exposing a health check tool with planned tools for listing resources and checking free tier.7-