aws-safe-mcp

Changelog · Quickstart · Troubleshooting

Safe, read-only AWS investigation tools for AI coding agents.

aws-safe-mcp is a local, read-only MCP server for investigating AWS resources without exposing a raw AWS SDK escape hatch. It gives AI clients structured, bounded tools for debugging serverless workloads while preserving IAM as the authorization boundary.

Status: alpha. The server is intentionally read-only in v1, and tool outputs are designed for investigation rather than complete AWS inventory export.

Use it to:

• Trace serverless dependencies across Lambda, EventBridge, Step Functions, and API Gateway.
• Trace Lambda VPC egress paths to understand inferred internet and private network reachability.
• Inspect recent failure signals without exposing secrets or raw payloads.
• Check permission paths with IAM simulation when available.
• Give AI clients useful AWS context without handing them a raw SDK shell.

Install In An AI Client

Use the published package with any MCP client that supports stdio:

Create ~/.config/aws-safe-mcp/config.yaml first (see Quickstart) — uvx will fail without it.

uvx aws-safe-mcp \
  --profile dev \
  --region eu-west-2 \
  --readonly \
  --config ~/.config/aws-safe-mcp/config.yaml

Client-specific setup:

• Claude Code
• Claude Desktop
• Cursor
• Provider-neutral notes

flowchart LR
    Client["AI client"] --> MCP["aws-safe-mcp"]
    MCP --> Guardrails["account allowlist\nread-only tools\nredaction"]
    Guardrails --> AWS["AWS metadata APIs"]
    AWS --> Summary["bounded summaries\ndependency graphs\npermission checks"]
    Summary --> Client

Why This Exists

AI clients are useful for debugging AWS systems, but a raw AWS SDK or CLI passthrough gives them too much power and too little context. aws-safe-mcp keeps the useful part: curated tools that answer common investigation questions about Lambda, Step Functions, API Gateway, EventBridge, S3, DynamoDB, and CloudWatch.

Good questions for this server:

• Which AWS resources are connected to this workload?
• What failed recently, and which signal should I inspect next?
• Does an execution role or resource policy appear to allow the expected path?
• Am I looking at the intended AWS account before resource calls run?

How This Differs From AWS MCP

The official AWS MCP server is the right tool for broad AWS access, current AWS documentation, and general cloud operations. aws-safe-mcp is deliberately narrower: it is a read-only diagnostic layer for serverless workloads.

Use both when that helps. Let AWS MCP handle general AWS API and documentation questions, and use aws-safe-mcp when you want bounded investigation results that are already shaped for AI reasoning.

Need	Best fit
Ask current AWS documentation questions	AWS MCP
Explore broad AWS APIs and services	AWS MCP
Trace Lambda, EventBridge, Step Functions, or API Gateway dependencies	aws-safe-mcp
Check IAM permission paths with concise verdicts	aws-safe-mcp
Diagnose recent serverless failure signals without raw payloads	aws-safe-mcp
Keep AI clients away from generic AWS API passthrough	aws-safe-mcp

The goal is not to replace AWS MCP. The goal is to add a safer, opinionated diagnostic layer beside it.

Safety Promises

aws-safe-mcp is read-only by construction: no generic SDK passthrough, no write-capable AWS verbs in v1, no S3 object body or DynamoDB item reads, and no disclosure of secrets, SSM parameter values, or Lambda environment values. Every tool call runs against an explicitly allowlisted AWS account, is audit logged as structured JSON to stderr, and has its returned strings redacted and bounded.

Full rules and the gating tests live in docs/standards.md.

See docs/limitations.md for known limitations and safety tradeoffs.

Demo

💡 Investigation Scenarios

The real power of aws-safe-mcp is in its ability to connect seemingly separate parts of an application's architecture into a single, digestible narrative for AI clients. Instead of simply listing resources, use these prompts to guide your investigation:

1. Tracing Event Flows (Lambda & EventBridge)

• Goal: Understand the end-to-end path when an object is created in S3 and triggers subsequent processing steps.
• Prompt Example: Trace the event flow for source aws.s3, detail type Object Created, bucket <bucket-name>, and .csv object keys. Use AWS MCP only.
• What it shows: The full dependency chain from the trigger (S3) -> rule match (EventBridge) -> target execution (Lambda/Step Functions).

2. Diagnosing Failure Points (Lambda & IAM)

• Goal: Pinpoint why a specific background job failed, without needing access to sensitive logs or raw payloads.
• Prompt Example: A Lambda function <function-name> is failing intermittently. Check the associated resource policies and dependency paths for common failure reasons like missing permissions or wrong resource ARNs.
• What it shows: A consolidated check of required IAM permissions, potential policy gaps (iam:GetPolicy), and whether the execution environment has necessary connectivity (e.g., VPC access).

3. Data Access Review (S3 & DynamoDB)

• Goal: Verify that an application component is only accessing data it should, ensuring least privilege at the metadata level.
• Prompt Example: Examine the expected read/write patterns for DynamoDB table <table-name> and S3 bucket <bucket-name>. Report if the required access pattern can be achieved with minimal permissions.
• What it shows: A summary of the services involved, potential permission mismatches (IAM simulation), and confirmation that data access paths are correctly bounded.

Quickstart

Install from a local checkout:

uv sync
uv run aws-safe-mcp --help

Create a local config file, for example ~/.config/aws-safe-mcp/config.yaml:

allowed_account_ids:
  - "123456789012"

readonly: true

For local AWS-compatible emulators, configure an endpoint explicitly:

allowed_account_ids:
  - "000000000000"

readonly: true

endpoint_url: http://127.0.0.1:4566

Use service_endpoint_urls only when a service needs a different endpoint:

service_endpoint_urls:
  s3: http://127.0.0.1:4572

Run the server with a non-production AWS profile:

uv run aws-safe-mcp \
  --profile dev \
  --region eu-west-2 \
  --readonly \
  --config ~/.config/aws-safe-mcp/config.yaml

After package publication, the intended runtime shape is:

uvx aws-safe-mcp \
  --profile dev \
  --region eu-west-2 \
  --readonly \
  --config ~/.config/aws-safe-mcp/config.yaml

In an MCP client, start with:

Check my AWS auth status. Use AWS MCP only.

Then try an investigation prompt:

Search AWS resources for <name-fragment>. Use AWS MCP only.

Explain the dependencies for Lambda <function-name>. Use AWS MCP only.

Trace network access for Lambda <function-name>. Use AWS MCP only.

Trace the event-driven flow for source aws.s3, detail type Object Created, bucket <bucket-name>, and .csv object keys. Use AWS MCP only.

Feedback and Ideas

Found a rough edge or want a new investigation tool? Start with docs/limitations.md to see whether the constraint is already known and intentional.

If it is not, file a GitHub issue at https://github.com/harryhazza77/aws-safe-mcp/issues/new using the templates in .github/ISSUE_TEMPLATE/ — feature.md for a new capability request, and limitation.md to report a behavior that surprises you so we can either fix it or document it.

Tools

The server includes identity, inventory, dependency, permission-checking, and failure-investigation tools for:

• Lambda, including dependency, failure, permission, and network access tracing
• Step Functions
• S3 metadata
• DynamoDB metadata
• CloudWatch Logs
• API Gateway
• EventBridge
• Cross-service resource search

See docs/tools.md for the full tool catalog, inputs, and shared dependency graph contract.

Client Setup Details

Provider-neutral setup notes:

• AI client notes
• Claude Code
• Claude Desktop
• Cursor

Claude Desktop example:

{
  "mcpServers": {
    "aws": {
      "command": "uvx",
      "args": [
        "aws-safe-mcp",
        "--profile",
        "dev",
        "--region",
        "eu-west-2",
        "--readonly",
        "--config",
        "~/.config/aws-safe-mcp/config.yaml"
      ]
    }
  }
}

AWS Authentication

Use an existing AWS config profile. The MCP server can start before login, so this is fine:

uvx aws-safe-mcp --profile dev --region eu-west-2 --readonly --config ~/.config/aws-safe-mcp/config.yaml

If get_aws_auth_status reports authenticated: false, authenticate normally:

aws login --profile dev
# or:
aws sso login --profile dev

The next get_aws_auth_status or AWS tool call re-checks STS. You do not need to restart the MCP server.

Permissions

Grant only the read actions needed for the tools you plan to use. Common actions include:

• Identity: sts:GetCallerIdentity
• Lambda: lambda:ListFunctions, lambda:GetFunctionConfiguration, lambda:ListAliases, lambda:ListEventSourceMappings, lambda:GetPolicy
• IAM checking: iam:GetRole, iam:ListAttachedRolePolicies, iam:ListRolePolicies, iam:SimulatePrincipalPolicy
• Logs and metrics: cloudwatch:GetMetricData, logs:DescribeLogGroups, logs:FilterLogEvents
• EventBridge: events:ListEventBuses, events:ListRules, events:DescribeRule, events:ListTargetsByRule
• Step Functions: states:ListStateMachines, states:DescribeStateMachine, states:DescribeExecution, states:GetExecutionHistory
• Metadata only: s3:ListAllMyBuckets, s3:ListBucket, s3:GetBucketLocation, dynamodb:ListTables, dynamodb:DescribeTable, apigateway:GET

Some dependency tools can return richer results when optional read permissions for SQS, SNS, S3 bucket settings, or IAM simulation are available. Missing optional permissions should produce warnings rather than failing the whole investigation.

Development

Run the local verification suite:

uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run bandit -q -r src
uv run pip-audit
uv run pytest --cov=aws_safe_mcp --cov-report=term-missing
uv run aws-safe-mcp --help
uv build
uvx --from . aws-safe-mcp --help

More development and release details:

• Development guide
• Architecture
• Release checklist
• Documentation index

Release Safety

Before publishing or tagging a release:

• Run the full verification suite.
• Inspect source and wheel package contents.
• Run a live MCP smoke test in a non-production AWS account when available.
• Confirm examples use fake account IDs and generic profile names.
• Confirm no local profile names, account IDs, ARNs, credentials, logs, or resource names are committed.

See docs/release.md for the complete release runbook.

Discoverability Checklist

When publishing on GitHub, set the repository description to:

Safe, read-only MCP server for AWS investigation by AI coding agents

Suggested topics:

mcp, aws, ai-agents, model-context-protocol, lambda, serverless, cloudwatch,
eventbridge, step-functions, developer-tools, security