awslabs.cloudwatch-appsignals-mcp-server 0.1.5

An AWS Labs Model Context Protocol (MCP) server for AWS Application Signals

CloudWatch Application Signals MCP Server

An MCP (Model Context Protocol) server that provides tools for monitoring and analyzing AWS services using AWS Application Signals.

This server enables AI assistants like Claude, GitHub Copilot, and Amazon Q to help you monitor service health, analyze performance metrics, track SLO compliance, and investigate issues using distributed tracing.

Key Features

1. Monitor overall service health, diagnose root causes, and recommend actionable fixes with the built-in APM expertise.
2. Generate business insights from telemetry data through natural language queries.

Prerequisites

1. Sign-Up for an AWS account
2. Enable Application Signals for your applications
3. Install uv from Astral or the GitHub README
4. Install Python using uv python install 3.10

Available Tools

1. list_monitored_services - List all services monitored by AWS Application Signals

   • Get an overview of all monitored services
   • See service names, types, and key attributes
   • Identify the services monitored by Application Signals

2. get_service_detail - Get detailed information about a specific service

   • Get Service key properties such as Hosting environment, list of APIs,etc
   • Get the list of ApplicationSignals metrics available on service
   • Find associated log groups

3. list_slis - List all SLOs and SLIs status for all services

   • List the configured SLOs and across all services
   • Find out all breached SLIs and status

4. get_slo - Gets the details configuration for a specific SLO

   • Return the relevant metrics info, SLO threshold

5. search_transaction_spans - Queries OTel Spans data via Transaction Search

   • Query OTel Spans to root cause the potential problems
   • Generate business performance insights summaries

6. query_sampled_traces - Queries AWS X-Ray traces to gain deeper insights

   • Find the impact from the tracing dependency view
   • Return the exact error stack for LLM to suggest the actionable fixes

7. query_service_metrics - Queries Application Signals metrics for root causing service performance issues

   • Query Application Signals RED metrics to correlate the relevant OTel Spans/Traces for troubleshooting

Installation

One-Click Installation

Cursor	VS Code

Installing via uv

When using uv no specific installation is needed. We will use uvx to directly run awslabs.cloudwatch-appsignals-mcp-server.

Installing for Amazon Q (Preview)

• Start Amazon Q Developer CLI from here.
• Add the following configuration in ~/.aws/amazonq/mcp.json file.

{
  "mcpServers": {
    "awslabs.cloudwatch-appsignals-mcp": {
      "autoApprove": [],
      "disabled": false,
      "command": "uvx",
      "args": [
        "awslabs.cloudwatch-appsignals-mcp-server@latest"
      ],
      "env": {
        "AWS_PROFILE": "[The AWS Profile Name to use for AWS access]",
        "AWS_REGION": "[AWS Region]",
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "transportType": "stdio"
    }
  }
}

Installing via Claude Desktop

On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

Development/Unpublished Servers Configuration

When installing a development or unpublished server, add the `--directory` flag:

{
  "mcpServers": {
    "awslabs.cloudwatch-appsignals-mcp-server": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/cloudwatch-appsignals-mcp-server", "awslabs.cloudwatch-appsignals-mcp-server"],
      "env": {
        "AWS_PROFILE": "[The AWS Profile Name to use for AWS access]",
        "AWS_REGION": "[AWS Region]"
      }
    }
  }
}

Published Servers Configuration

{
  "mcpServers": {
    "awslabs.cloudwatch-appsignals-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.cloudwatch-appsignals-mcp-server@latest"],
      "env": {
        "AWS_PROFILE": "[The AWS Profile Name to use for AWS access]",
        "AWS_REGION": "[AWS Region]"
      }
    }
  }
}

Build and install docker image locally on the same host of your LLM client

1. git clone https://github.com/awslabs/mcp.git
2. Go to sub-directory 'src/cloudwatch-appsignals-mcp-server/'
3. Run 'docker build -t awslabs/cloudwatch-appsignals-mcp-server:latest .'

Add or update your LLM client's config with following:

{
  "mcpServers": {
    "awslabs.cloudwatch-appsignals-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "${HOME}/.aws:/root/.aws:ro",
        "-e", "AWS_PROFILE=[The AWS Profile Name to use for AWS access]",
        "-e", "AWS_REGION=[AWS Region]",
        "awslabs/cloudwatch-appsignals-mcp-server:latest"
      ]
    }
  }
}

Debugging

You can use the MCP inspector to debug the server. For uvx installations:

npx @modelcontextprotocol/inspector uvx awslabs.cloudwatch-appsignals-mcp-server

Or if you've installed the package in a specific directory:

cd /path/to/cloudwatch-appsignals-mcp-server
npx @modelcontextprotocol/inspector uv run awslabs.cloudwatch-appsignals-mcp-server

Usage Examples

Example 1: Getting Started with Service Monitoring

User: "What services are being monitored by Application Signals?"
Assistant: I'll check what services are currently being monitored by AWS Application Signals.

[Uses list_monitored_services tool]

I found 3 services being monitored:

• Service: api-gateway-service
  Type: AWS::ApiGateway::RestApi
  Key Attributes:
    Name: api-gateway-service
    Type: AWS::ApiGateway::RestApi
    Environment: production

• Service: order-service
  Type: AWS::ECS::Service
  Key Attributes:
    Name: order-service
    Type: AWS::ECS::Service
    Environment: production
    Platform: ECS

• Service: payment-lambda
  Type: AWS::Lambda::Function
  Key Attributes:
    Name: payment-lambda
    Type: AWS::Lambda::Function
    Environment: production

Example 2: Investigating Service Details

User: "Tell me more about the order-service"
Assistant: I'll get detailed information about the order-service.

[Uses get_service_detail tool]

Here are the details for order-service:

Key Attributes:
  Name: order-service
  Type: AWS::ECS::Service
  Environment: production

Additional Attributes:
  Platform: ECS
  Application: ecommerce-app
  Telemetry.SDK: opentelemetry-1.9.0

Metric References (15 total):
  • AWS/ApplicationSignals/Latency
    Type: GAUGE
    Dimensions: Service=order-service, Operation=GetOrder

  • AWS/ApplicationSignals/ErrorRate
    Type: GAUGE
    Dimensions: Service=order-service, Operation=CreateOrder

Log Group References (2 total):
  • /aws/ecs/order-service
  • /aws/application-signals/order-service

Configuration

Required AWS Permissions

The server requires the following AWS IAM permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "application-signals:ListServices",
        "application-signals:GetService",
        "application-signals:ListServiceLevelObjectives",
        "application-signals:GetServiceLevelObjective",
        "application-signals:BatchGetServiceLevelObjectiveBudgetReport",
        "cloudwatch:GetMetricData",
        "logs:GetQueryResults",
        "logs:StartQuery",
        "logs:StopQuery",
        "xray:GetTraceSummaries",
        "xray:BatchGetTraces"
      ],
      "Resource": "*"
    }
  ]
}

Environment Variables

• AWS_PROFILE - AWS profile name to use for authentication (defaults to default profile)
• AWS_REGION - AWS region (defaults to us-east-1)
• MCP_CLOUDWATCH_APPSIGNALS_LOG_LEVEL - Logging level (defaults to INFO)

AWS Credentials

This server uses AWS profiles for authentication. Set the AWS_PROFILE environment variable to use a specific profile from your ~/.aws/credentials file.

The server will use the standard AWS credential chain via boto3, which includes:

• AWS Profile specified by AWS_PROFILE environment variable
• Default profile from AWS credentials file
• IAM roles when running on EC2, ECS, Lambda, etc.

Development

This server is part of the AWS Labs MCP collection. For development and contribution guidelines, please see the main repository documentation.

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.