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

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

概述

AWS MCP 服务器提供了一个 MCP 感知 AI 助手（如 Claude Desktop、Cursor、Windsurf）和 AWS CLI 之间的桥梁。它使这些助手能够：

1. 检索 AWS CLI 文档 - 获取有关 AWS 服务和命令的详细帮助
2. 执行 AWS CLI 命令 - 运行命令并接收针对 AI 消费优化的格式化结果

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

演示

演示

该视频演示了如何使用 Claude Desktop 和 AWS MCP Server 创建一个安装了 AWS SSM 代理的新 AWS EC2 实例。

特性

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

要求

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

入门

运行服务器选项 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-abc123: 开发构建版本，使用 Git 提交 SHA 标记

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

# 克隆存储库
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_MCP_TIMEOUT	命令执行超时时间（秒）	300
AWS_MCP_MAX_OUTPUT	最大输出大小（字符数）	100000
AWS_MCP_TRANSPORT	要使用的传输协议（“stdio”或“sse”）	stdio
AWS_PROFILE	要使用的 AWS 配置文件	default
AWS_REGION	要使用的 AWS 区域	us-east-1

与 Claude Desktop 集成

选项 1：使用 Smithery（最简单）

为 Claude Desktop 安装和配置 AWS MCP Server 的最简单方法是通过 Smithery:

npx -y @smithery/cli install @alexei-led/aws-mcp-server --client claude

此命令将自动配置 Claude Desktop 以使用 AWS MCP Server。

选项 2：手动配置

要手动将 AWS MCP Server 与 Claude Desktop 集成：

1. 找到 Claude Desktop 配置文件:

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

2. 编辑配置文件 以包含 AWS MCP Server：

   {
     "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 Server 可用

flowchart TD
    subgraph "用户设备"
        config[编辑 claude_desktop_config.json]
        claude[Claude Desktop]
        docker[Docker 容器]
        aws_creds[AWS 凭证]
    end
    
    subgraph "AWS 云"
        services[AWS 服务]
    end
    
    config -->|添加 MCP 服务器配置| claude
    claude -->|Docker 运行命令| docker
    aws_creds -->|只读挂载| docker
    docker -->|API 调用| services

示例交互

获取 AWS CLI 文档:

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

Claude: 让我为您获取该信息。

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

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

SYNOPSIS
    cp <LocalPath> <S3Uri> or <S3Uri> <LocalPath> or <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

使用提示模板:

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

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

以下是执行全面安全审计的 AWS CLI 命令：

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

# 检查存储桶策略是否存在公共访问
aws s3api list-buckets --query 'Buckets[*].Name' --output text | xargs -I {} aws s3api get-bucket-policy --bucket {} 2>/dev/null

# 识别没有加密的存储桶
aws s3api list-buckets --query 'Buckets[*].Name' --output text | xargs -I {} aws s3api get-bucket-encryption --bucket {} 2>/dev/null

# 检查是否启用了存储桶日志记录
aws s3api list-buckets --query 'Buckets[*].Name' --output text | xargs -I {} aws s3api get-bucket-logging --bucket {} 2>/dev/null

# 验证存储桶版本控制状态
aws s3api list-buckets --query 'Buckets[*].Name' --output text | xargs -I {} aws s3api get-bucket-versioning --bucket {}

可用提示模板

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

提示	描述	参数
create_resource	生成使用最佳实践创建 AWS 资源的命令	resource_type, resource_name
security_audit	审计特定 AWS 服务的安全设置	service
cost_optimization	查找服务的成本优化机会	service
resource_inventory	创建资源的全面清单	service, region (可选)
troubleshoot_service	生成用于排除服务问题的命令	service, resource_id
iam_policy_generator	创建最小权限 IAM 策略	service, actions, resource_pattern (可选)
service_monitoring	设置全面监控	service, metric_type (可选)
disaster_recovery	实施灾难恢复解决方案	service, recovery_point_objective (可选)
compliance_check	检查是否符合标准	compliance_standard, service (可选)
resource_cleanup	识别并安全地清理资源	service, criteria (可选)

安全

• 服务器使用来自主机的 AWS 凭证
• 所有命令在执行前都经过验证
• 超时限制可防止长时间运行的命令
• 命令必须以“aws”前缀开头
• 限制潜在的危险命令

开发

设置开发环境

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

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

# 运行单元测试
pytest -k "not integration"

# 运行带有覆盖率报告的测试
pytest -k "not integration" --cov-report=html

# 运行 linting
ruff check src/ tests/

# 运行格式化
ruff format src/ tests/

代码覆盖率

该项目包含 Codecov 的配置，用于跟踪代码覆盖率指标。 该配置位于 codecov.yml 文件中，该文件：

• 设置 80% 的目标覆盖率阈值
• 从覆盖率报告中排除测试文件、设置文件和文档
• 配置 PR 注释和状态检查

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

集成测试

集成测试验证 AWS MCP Server 是否与实际 AWS 资源正确配合使用。 要运行它们：

1. 设置 AWS 资源:

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

2. 运行集成测试:

   # 运行包括集成测试在内的所有测试
   pytest --run-integration
   
   # 仅运行集成测试
   pytest --run-integration -m integration
   

故障排除

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

为什么使用 Docker 部署

安全优势

• 隔离: Docker 容器提供完全隔离 - AWS CLI 命令和实用程序在受控环境中运行，而不是直接在您的本地计算机上运行
• 受控访问: 容器仅对您的 AWS 凭证具有只读访问权限
• 无需本地安装: 避免直接在您的主机系统上安装 AWS CLI 和支持工具
• 干净的环境: 每次容器运行都从一个原始的、正确配置的环境开始

可靠性优势

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

其他优势

• 多架构支持: 在 Intel/AMD (x86_64) 和 ARM (Apple Silicon, 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 文件。