AWS 模型上下文协议 (MCP) 服务器

一个轻量级的服务，使 AI 助手能够通过模型上下文协议 (MCP) 执行 AWS CLI 命令。

概述

AWS MCP 服务器在 MCP 兼容 AI 助手（如 Claude Desktop、Cursor、Windsurf）和 AWS CLI 之间架起桥梁。它使这些助手能够：

1. 检索 AWS CLI 文档 (aws_cli_help) - 获取有关 AWS 服务和命令的详细信息
2. 执行 AWS CLI 命令 (aws_cli_pipeline) - 使用 Unix 管道运行命令，并接收针对 AI 优化的格式化结果

flowchart LR
    AI[AI 助手] <-->|MCP 协议| Server[AWS MCP 服务器]
    Server <-->|子进程| AWS[AWS CLI]
    AWS <-->|API| Cloud[AWS 云]

演示

演示

视频演示了使用 Claude Desktop 和 AWS MCP 服务器创建带有 AWS SSM 代理的新 AWS EC2 实例。

功能

• 命令文档 - AWS CLI 命令的详细帮助信息
• 命令执行 - 执行 AWS CLI 命令并返回人类可读的结果
• Unix 管道支持 - 使用标准 Unix 管道和工具过滤和转换 AWS CLI 输出
• AWS 资源上下文 - 通过 MCP 资源访问 AWS 配置文件、区域、账户信息和环境详情
• 提示模板 - 遵循最佳实践的常见 AWS 任务的预定义提示模板
• Docker 集成 - 通过容器化进行简单部署，支持多架构（AMD64/x86_64 和 ARM64）
• AWS 身份验证 - 利用主机机的现有 AWS 凭证

要求

• Docker（默认）或 Python 3.13+（以及本地安装的 AWS CLI）
• 配置 AWS 凭证

入门指南

注意： 出于安全性和可靠性考虑，在 Docker 容器中运行服务器是强烈推荐的方法。请查阅安全注意事项部分以了解重要考虑事项。

运行服务器选项 1：使用 Docker（推荐）

# 克隆仓库
git clone https://github.com/alexei-led/aws-mcp-server.git
cd aws-mcp-server

# 构建 Docker 容器并运行
docker compose -f deploy/docker/docker-compose.yml up -d

Docker 镜像支持 AMD64/x86_64（Intel/AMD）和 ARM64（Apple Silicon M1-M4、AWS Graviton）架构。

注意：来自 GitHub Packages 的官方镜像支持多架构，将自动使用适合您系统的版本。

# 使用最新稳定版本
docker pull ghcr.io/alexei-led/aws-mcp-server:latest

# 或指定特定版本（推荐用于生产环境）
docker pull ghcr.io/alexei-led/aws-mcp-server:1.0.0

Docker 镜像标签：

• latest：最新稳定版本
• x.y.z（例如，1.0.0）：特定版本
• sha-<commit-sha>：开发构建，使用 Git 提交 SHA 标记（例如，sha-gb697684）

运行服务器选项 2：使用 Python

谨慎使用：原生运行需要仔细设置环境，与推荐的 Docker 部署相比，安全性风险更高。确保您理解安全注意事项部分概述的影响。

# 克隆仓库
git clone https://github.com/alexei-led/aws-mcp-server.git
cd aws-mcp-server

# 设置虚拟环境
python -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate

# 以开发模式安装
pip install -e .

# 运行服务器
python -m aws_mcp_server

配置

AWS MCP 服务器可以使用环境变量进行配置：

重要： 安全管理提供给服务器的 AWS 凭证，无论是通过挂载的 ~/.aws 文件还是环境变量。确保凭据遵循安全注意事项部分详细说明的最小权限原则。在 Docker 中运行时，请确保这些变量正确传递到容器环境（例如，使用 docker run -e VAR=value ...）。

安全注意事项

在针对您的 AWS 环境执行命令时，安全性至关重要。虽然 AWS MCP 服务器提供了功能，但您有责任安全地配置和运行它。请严格遵守以下内容：

1. 推荐的部署：Docker 容器

• 隔离： 在 Docker 容器中运行服务器是强烈推荐且默认的部署方法。容器化提供了关键的文件系统和处理隔离。即使执行了破坏性 Unix 命令（如 rm、mv），即使被误用，也将在短暂的 Docker 环境中受到限制，并且不会影响您的主机机的文件系统。容器可以轻松停止并重新创建。
• 受控环境： Docker 确保了一致的环境和必要的依赖项，减少了意外行为。

2. AWS 凭证和 IAM 最小权限（关键）

• 用户责任： 您向服务器提供 AWS 凭证（通过挂载 ~/.aws 或环境变量）。
• 最小权限至关重要： 服务器使用您提供的凭据执行 AWS CLI 命令。绝对关键的是，这些凭据属于一个 IAM 实体（用户或角色），其权限配置为仅对您通过此工具意图执行的 AWS 操作具有最小必要权限（最小权限）。
  • 切勿使用根凭证： 绝对不要使用 AWS 账户根用户凭证。
  • 定期审查权限： 定期审计与关联的 IAM 权限。
• 影响限制： 正确配置的 IAM 权限是主要机制，用于限制通过服务器执行的任何命令的潜在影响，无论是故意还是无意。即使命令被操纵，它也只能执行特定 IAM 策略允许的操作。

3. 受信任用户模型

• 服务器假设与 MCP 客户端（例如，Claude Desktop、Cursor）交互的最终用户是同一个受信任的个人，他配置了服务器并提供了最小权限的 AWS 凭证。不要将服务器或连接的客户端暴露给不受信任的用户。

4. 理解执行风险（当前实现）

• 命令执行： 当前实现使用 shell 功能（子进程调用中的 shell=True）来执行 AWS 命令并处理 Unix 管道。虽然方便，但这种方法如果输入命令字符串被操纵，则存在固有风险（命令注入）。
• 操作控制缓解： 在受信任用户模型和 Docker 部署的上下文中，这些风险通过操作控制得到缓解：
  • 受信任用户不会提供针对其自身环境的故意恶意命令。
  • Docker 包含文件系统副作用。
  • 关键在于，IAM 最小权限限制了任何可执行的 AWS 操作的范围。
• 凭证泄露风险： 尽管容器化并使用 IAM，但复杂的命令注入可能会尝试读取挂载的凭证（~/.aws）或环境变量，并尝试泄露（例如，通过 curl）。严格的 IAM 策略仍然是防御此类凭证泄露价值的最重要手段。

5. 网络暴露（SSE 传输）

• 如果使用 sse 传输（这意味着有一个网络监听器），请确保仅绑定到受信任的网络接口（例如，localhost）或如果您更广泛地公开它，则实施适当的网络安全控制（防火墙、身份验证代理）。默认的 stdio 传输不会打开网络端口。

6. 责任共担总结

• AWS MCP 服务器提供工具。
• 您，用户，负责：
  • 在推荐的 Docker 环境中运行它。
  • 提供并安全管理最小权限的 AWS 凭证。
  • 确保只有受信任的用户与服务器/客户端交互。
  • 保护网络环境（如果适用）。

通过严格遵守 Docker 部署和细致的 IAM 最小权限配置，您建立了使用当前实现的 AWS MCP 服务器安全运行所需的操作控制。

与 Claude Desktop 集成

配置

要手动将 AWS MCP 服务器与 Claude Desktop 集成：

1. 定位 Claude Desktop 配置文件：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. 编辑配置文件以包含 AWS MCP 服务器：

   {
     "mcpServers": {
       "aws-mcp-server": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "-v",
           "/Users/YOUR_USER_NAME/.aws:/home/appuser/.aws:ro",
           "ghcr.io/alexei-led/aws-mcp-server:latest"
         ]
       }
     }
   }
   

3. 重启 Claude Desktop 以应用更改

   • 重启后，您应该在输入框右下角看到一个锤子 🔨 图标
   • 这表示 AWS MCP 服务器可用

flowchart TD
    subgraph "用户设备"
        config[编辑 claude_desktop_config.json]
        claude[Claude Desktop]
        docker[Docker 容器]
        aws_creds[AWS 凭证]
    end
    
    subgraph "AWS 云"
        services[AWS 服务]
    end
    
    subgraph "MCP 服务器组件"
        tools[AWS CLI 工具]
        resources[AWS 资源]
        templates[提示模板]
    end
    
    config -->|添加 MCP 服务器配置| claude
    claude -->|Docker Run 命令| docker
    docker --- tools
    docker --- resources
    docker --- templates
    aws_creds -.->|挂载只读| docker
    resources -.->|读取| aws_creds
    tools -->|API 调用| services

示例交互

获取 AWS CLI 文档:

用户: AWS S3 cp 命令有哪些可用选项？

Claude: 让我为您获取这些信息。

AWS S3 cp 命令具有以下选项：

NAME
    cp - 复制本地文件或 S3 对象到本地或 S3 的另一个位置。

SYNOPSIS
    cp <LocalPath> <S3Uri> 或 <S3Uri> <LocalPath> 或 <S3Uri> <S3Uri> [--acl <value>] [--cache-control <value>] ...

执行 AWS CLI 命令:

用户: 列出我的 S3 存储桶

Claude: 我将为您列出我的 S3 存储桶。

2023-10-15 14:30:45 my-bucket-1
2023-11-20 09:15:32 my-bucket-2
2024-01-05 11:22:18 my-backup-bucket

使用命令管道:

用户: 列出名称中包含 "backup" 的我的 S3 存储桶，并按字母顺序显示它们

Claude: 让我为您找到这些。

2024-01-05 11:22:18 my-backup-bucket
2024-03-01 09:44:12 weekly-backup-bucket
2024-03-15 13:10:57 database-backup-bucket

访问 AWS 资源:

用户: 有哪些 AWS 区域可供我使用？

Claude: 让我检查一下可供您使用的 AWS 区域。

可用区域：
- us-east-1 (US East, N. Virginia) - 目前已选择
- us-east-2 (US East, Ohio)
- us-west-1 (US West, N. California)
- us-west-2 (US West, Oregon)
- eu-west-1 (EU West, Ireland)
- eu-central-1 (EU Central, Frankfurt)
- ap-northeast-1 (亚洲太平洋, Tokyo)
- ap-southeast-1 (亚洲太平洋, Singapore)
- ap-southeast-2 (亚洲太平洋, Sydney)

您目前使用的是 us-east-1 区域。

使用提示模板:

用户: 我需要对我的 S3 存储桶进行安全审计

Claude: 我将帮助您审计我的 S3 存储桶的安全设置。

以下遵循最佳实践的常见 AWS 任务的预定义提示模板：

# 列出具有公共访问设置的 S3 存储桶
aws s3api list-buckets --query 'Buckets[*].Name' --output text | xargs -I {} aws s3api get-public-access-block --bucket {}

可用的提示模板

AWS MCP 服务器包含以下预定义提示模板：

核心操作

安全与合规

成本与性能

基础设施与架构

可靠性与监控

安全

AWS MCP 服务器实现了全面的分层方法来验证命令并确保安全：

命令验证系统

服务器通过三层系统验证所有 AWS CLI 命令：

1. 基本命令结构：

   • 验证命令以 'aws' 开头并包含有效的服务
   • 确保正确的命令语法

2. 以安全为重点的命令过滤：

   • 危险命令：阻止可能危及安全的命令
   • 安全模式：明确允许正常使用所需的只读操作
   • 正则表达式模式匹配：通过模式匹配防止复杂的网络安全风险

3. 管道命令安全：

   • 验证用于管道的 Unix 命令
   • 限制命令到安全的允许列表
   • 防止文件系统操作和任意命令执行

默认安全配置

默认安全配置侧重于防止以下攻击向量：

1. 身份和访问管理 (IAM) 风险

2. 审计和日志篡改

3. 敏感数据访问和保护

4. 网络安全风险

许多匹配这些模式的只读操作被明确允许：

• 所有 get-, list- 和 describe- 命令
• 所有帮助命令 (--help, help)
• 模拟和测试命令 (例如，aws iam simulate-custom-policy)

安全示例

系统遵循 IAM 最佳实践，专注于防止权限提升：

# 此命令将被阻止（创建用户）
aws iam create-user --user-name new-user
> 错误：此命令 (aws iam create-user) 出于安全原因被限制。

# 此命令将被阻止（附加管理员策略）
aws iam attach-user-policy --user-name any-user --policy-arn arn:aws:iam::aws:policy/AdministratorAccess
> 错误：附加 Administrator 策略被限制，因为权限提升。

# 此命令将被阻止（全局打开 SSH 端口）
aws ec2 authorize-security-group-ingress --group-id sg-12345 --protocol tcp --port 22 --cidr 0.0.0.0/0
> 错误：打开非 Web 端口到整个互联网 (0.0.0.0/0) 被限制。

# 这些命令被允许（只读操作）
aws iam list-users
aws s3 ls
aws ec2 describe-instances

安全最佳实践

• 始终使用默认的 strict 安全模式在生产环境中
• 遵循安全注意事项中的部署建议
• 以最小权限的 AWS 凭证运行
• 对于自定义配置，专注于您的安全需求

开发

设置开发环境

# 仅安装运行时依赖项使用 pip
pip install -e .

# 使用 pip 安装所有开发依赖项
pip install -e ".[dev]"

# 或使用 uv 进行更快的依赖管理
make uv-install       # 安装运行时依赖项
make uv-dev-install   # 安装开发依赖项

Makefile 命令

项目包含一个 Makefile，其中包含用于常见任务的多个目标：

# 测试命令
make test             # 运行测试（排除集成测试）
make test-unit        # 仅运行单元测试（仅单元测试）
make test-integration # 仅运行集成测试（需要 AWS 凭证）
make test-all         # 运行所有测试，包括集成测试

# 测试覆盖率命令
make test-coverage    # 运行测试并生成覆盖率报告（排除集成测试）
make test-coverage-all # 运行所有测试并生成覆盖率报告（包括集成测试）

# Linter 和格式化
make lint             # 运行 linter（ruff check 和 format --check）
make lint-fix         # 运行 linter 并尽可能自动修复问题
make format           # 使用 ruff 格式化代码

要获取可用命令的完整列表，请运行 make help。

代码覆盖率

项目包含 Codecov 的配置以跟踪代码覆盖率指标。配置在 codecov.yml 文件中，它：

• 设置目标覆盖率阈值为 80%
• 排除测试文件、设置文件和文档从覆盖率报告中
• 配置 PR 评论和 CI/CD 检查状态

在 CI/CD 运行期间自动生成覆盖率报告并上传到 Codecov。

集成测试

集成测试验证 AWS MCP 服务器与实际 AWS 资源正常工作。要运行它们：

1. 设置 AWS 资源:

   • 创建用于测试的 S3 存储桶
   • 设置环境变量：export AWS_TEST_BUCKET=your-test-bucket-name
   • 确保您的 AWS 凭证已配置

2. 运行集成测试:

   # 运行所有测试，包括集成测试
   make test-all
   
   # 仅运行集成测试
   make test-integration
   

或直接运行 pytest 命令：

# 运行所有测试，包括集成测试
pytest --run-integration

# 仅运行集成测试
pytest --run-integration -m integration

故障排除

• 身份验证问题：确保您的 AWS 凭证已正确配置
• 连接错误：验证服务器正在运行且 AI 助手连接设置正确
• 权限错误：检查您的 AWS 凭证具有必要的权限
• 超时错误：对于长时间运行的命令，增加 AWS_MCP_TIMEOUT 环境变量

为什么使用 Docker 部署

通过 Docker 部署 AWS MCP 服务器是推荐的方法，它提供了显著的安全和可靠性优势，构成了该工具安全使用模式的核心：

安全优势

• 隔离（主要缓解措施）：Docker 容器提供了关键的文件系统和处理隔离。AWS CLI 命令和管道 Unix 工具在受控环境中运行。文件系统副作用被限制在容器内，保护了您的主机机。
• 受控凭证访问：挂载凭证时使用 :ro 标签限制了容器访问您的 AWS 配置文件的能力。
• 无需本地安装：避免在主机机上安装 AWS CLI 及其依赖项。
• 干净的环境：每次容器运行都从已知、干净的状态开始。

可靠性优势

• 一致的配置：所有必要的工具（AWS CLI、SSM 插件、jq）都预装并正确配置。
• 依赖管理：避免了工具和依赖项之间的版本冲突。
• 跨平台一致性：在不同的操作系统上工作方式相同。
• 完整环境：包括用于命令管道、过滤和格式化的所有必要工具。

其他优势

• 多架构支持：支持 AMD64/x86_64（Intel/AMD）和 ARM64（Apple Silicon M1-M4、AWS Graviton）架构。
• 简单更新：通过单个拉取命令即可更新到新版本。
• 无 Python 环境冲突：避免了系统上其他 Python 应用程序的潜在冲突。
• 版本固定：可以轻松固定特定版本以在生产环境中保持稳定性。

版本控制

此项目使用 setuptools_scm 自动根据 Git 标签确定版本：

• 发布版本：当存在 Git 标签时（例如，1.2.3），版本将正好是那个标签。
• 开发版本：对于没有标签的提交，将生成开发版本，格式为： <last-tag>.post<commits-since-tag>+g<commit-hash>.d<date> (例如，1.2.3.post10+gb697684.d20250406)

版本自动包含在：

• 包含版本信息
• Docker 镜像标签
• 持续集成构建

创建发布版本

要创建新的发布版本：

# 创建并推送新标签
git tag -a 1.2.3 -m "发布版本 1.2.3"
git push origin 1.2.3

CI/CD 管道将自动构建并发布 Docker 镜像，并使用适当的版本标签。

有关版本管理系统的更多详细信息，请参阅 VERSION.md。

许可证

本项目根据 MIT 许可证授权 - 请查看 LICENSE 文件获取详细信息。