aws-observability-mcp-tools

FastMCP server exposing AWS observability tools to Claude via the Model Context Protocol built with Python, boto3, and FastMCP.

Overview

This project bridges Claude (or any MCP-compatible AI client) with live AWS infrastructure. Instead of manually querying the AWS console or CLI, you can ask Claude natural language questions and it will invoke the appropriate AWS API calls through this MCP server in real time.

Example:

"What AWS account am I running in and what region is active?" "Is my EC2 instance i-0a1b2c3d4e5f6 running?"

Claude decides which tool to call, passes the right parameters, and returns a coherent answer all powered by this server running locally.

Architecture

Claude (AI client)
      │
      │  MCP protocol (JSON-RPC over stdio)
      ▼
aws-observability-mcp-tools  ←── FastMCP server (Python)
      │
      │  boto3 API calls
      ▼
AWS (STS, EC2, ...)

Tools

Tool	AWS Service	Description
aws_whoami	STS	Returns current AWS identity account ID, ARN, and user/role
get_ec2_status	EC2	Returns the running state of a specified EC2 instance

More tools planned: CloudWatch metrics, S3 bucket inspection, Lambda function status.

Tech Stack

• Python 3.12
• FastMCP - MCP server framework
• boto3 - AWS SDK for Python
• botocore - AWS error handling (ClientError, BotoCoreError)

Prerequisites

• Python 3.10+
• AWS credentials configured (aws configure or environment variables)
• Claude Desktop or any MCP-compatible client

Setup

1. Clone the repo

git clone git@github.com:jmac052002/aws-observability-mcp-tools.git
cd aws-observability-mcp-tools

2. Create and activate a virtual environment

python3 -m venv .venv
source .venv/bin/activate

3. Install dependencies

pip install fastmcp boto3

4. Configure AWS credentials

aws configure

Or export environment variables:

export AWS_ACCESS_KEY_ID=your_key
export AWS_SECRET_ACCESS_KEY=your_secret
export AWS_DEFAULT_REGION=us-east-1

Running the Server

python main.py

The server starts and listens for MCP client connections over stdio.

Connecting to Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "aws-observability": {
      "command": "python",
      "args": ["/path/to/aws-observability-mcp-tools/main.py"]
    }
  }
}

Restart Claude Desktop and the AWS tools will be available in your conversations.

Error Handling

The server normalizes all AWS exceptions into clean JSON responses so Claude always receives structured, readable feedback:

• ClientError - invalid parameters, permission denied, resource not found
• BotoCoreError - low-level connectivity or configuration issues
• Generic exceptions - caught and returned with type and message

Project Status

Active development. This is a portfolio/learning project demonstrating MCP server implementation with real AWS service integration.

Author

Joseph McCoy · github.com/jmac052002