mcp-aws-observability-server

A small, dependency-free MCP (Model Context Protocol) server that exposes AWS CloudWatch Logs and Alarms as tools an LLM client (Claude Desktop, an agent runtime, a custom MCP client) can call — list_log_groups, search_logs, and get_active_alarms.

This is a reference implementation modelled on the kind of MCP server I've built and deployed to AWS at Equal Experts for centralized logging/monitoring/observability across a shared GenAI platform: the same tool surface, but standing on a mock backend here instead of a real account, so anyone can clone and run it in under a minute.

Why no SDK dependency

The official mcp SDK is great, but for a reference/demo repo I wanted zero install friction and the transport mechanics to be visible rather than hidden behind a library. src/mcp_observability/protocol.py implements the newline-delimited JSON-RPC 2.0 stdio transport and the initialize / tools/list / tools/call lifecycle directly from the MCP specification. It's ~200 lines and fully tested — a good place to actually read how MCP works under the hood.

Related MCP server: mcp-cloudwatch-explorer

Quickstart

git clone https://github.com/swapnilbabladkar/mcp-aws-observability-server.git
cd mcp-aws-observability-server

# run the test suite (stdlib unittest, no install required)
PYTHONPATH=src python3 -m unittest discover -s tests -v

# run the full stdio flow against a real subprocess
python3 examples/demo_client.py

# or run the server directly (reads JSON-RPC from stdin, writes to stdout)
PYTHONPATH=src python3 -m mcp_observability

Using it from Claude Desktop

Add to your MCP client config (e.g. Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "aws-observability": {
      "command": "python3",
      "args": ["-m", "mcp_observability"],
      "env": { "PYTHONPATH": "/absolute/path/to/mcp-aws-observability-server/src" }
    }
  }
}

Restart Claude Desktop and ask it something like "any active alarms on the platform right now?" or "search the mcp-server log group for errors in the last two hours."

Switching to real AWS data

By default the server runs on MockObservabilityBackend, which returns realistic canned data (log groups/events/alarms shaped like a real EKS-hosted MCP server + RAG pipeline platform) so the whole tool-call flow works with zero AWS setup.

To point it at a real account, install the optional AWS extra and swap the backend in server.py:

pip install -e ".[aws]"

# server.py
from .backends import AWSObservabilityBackend

def default_server() -> MCPServer:
    return build_server(AWSObservabilityBackend(region_name="eu-west-1"))

AWSObservabilityBackend (in backends.py) implements the same interface via boto3's logs and cloudwatch clients — real describe_log_groups / filter_log_events / describe_alarms calls, paginated. It needs a role/profile with logs:Describe*, logs:FilterLogEvents, and cloudwatch:DescribeAlarms.

Project layout

src/mcp_observability/
  protocol.py   # MCP JSON-RPC/stdio transport — the actual protocol implementation
  backends.py   # ObservabilityBackend interface + Mock and AWS implementations
  server.py     # registers the 3 tools against a backend
  __main__.py   # `python -m mcp_observability` entrypoint
tests/          # unittest coverage for protocol + mock backend
examples/
  demo_client.py  # spawns the server as a subprocess and drives it end-to-end

Running the tests

PYTHONPATH=src python3 -m unittest discover -s tests -v

16 tests, covering the JSON-RPC error cases (parse errors, unknown methods, unknown tools, tool-level failures vs. protocol failures) as well as the mock backend's filtering logic.

License

MIT — see LICENSE.