Metadata-Version: 2.4
Name: aws-safe-mcp
Version: 0.3.0
Summary: Read-only, opinionated MCP server for safely investigating AWS resources.
Project-URL: Homepage, https://github.com/harryhazza77/aws-safe-mcp
Project-URL: Repository, https://github.com/harryhazza77/aws-safe-mcp
Project-URL: Issues, https://github.com/harryhazza77/aws-safe-mcp/issues
Project-URL: Changelog, https://github.com/harryhazza77/aws-safe-mcp/blob/main/CHANGELOG.md
Project-URL: Security, https://github.com/harryhazza77/aws-safe-mcp/security/policy
Author: Haresh Patel
License: MIT
License-File: LICENSE
Keywords: aws,lambda,mcp,model-context-protocol,serverless
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Requires-Dist: boto3>=1.34.0
Requires-Dist: botocore[crt]>=1.34.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pyyaml>=6.0.1
Description-Content-Type: text/markdown

# aws-safe-mcp

[![CI](https://github.com/harryhazza77/aws-safe-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/harryhazza77/aws-safe-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/aws-safe-mcp.svg)](https://pypi.org/project/aws-safe-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/aws-safe-mcp.svg)](https://pypi.org/project/aws-safe-mcp/)

[Changelog](CHANGELOG.md) · [Quickstart](docs/quickstart.md) · [Troubleshooting](docs/troubleshooting.md)

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](docs/quickstart.md)) — `uvx` will fail without it.

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

Client-specific setup:

- [Claude Code](docs/claude-code.md)
- [Claude Desktop](docs/claude-desktop.md)
- [Cursor](docs/cursor.md)
- [Provider-neutral notes](docs/ai-clients.md)

```mermaid
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`](docs/standards.md).

See [docs/limitations.md](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:

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

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

```yaml
allowed_account_ids:
  - "123456789012"

readonly: true
```

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

```yaml
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:

```yaml
service_endpoint_urls:
  s3: http://127.0.0.1:4572
```

Run the server with a non-production AWS profile:

```bash
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:

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

In an MCP client, start with:

```text
Check my AWS auth status. Use AWS MCP only.
```

Then try an investigation prompt:

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

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

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

```text
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`](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](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](docs/tools.md) for the full tool catalog, inputs, and shared
dependency graph contract.

## Client Setup Details

Provider-neutral setup notes:

- [AI client notes](docs/ai-clients.md)
- [Claude Code](docs/claude-code.md)
- [Claude Desktop](docs/claude-desktop.md)
- [Cursor](docs/cursor.md)

Claude Desktop example:

```json
{
  "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:

```bash
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:

```bash
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:

```bash
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](docs/development.md)
- [Architecture](docs/architecture.md)
- [Release checklist](docs/release.md)
- [Documentation index](docs/README.md)

## 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](docs/release.md) for the complete release runbook.

## Discoverability Checklist

When publishing on GitHub, set the repository description to:

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

Suggested topics:

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