AWS DynamoDB MCP Server

AWS DynamoDB MCP 服务器

Amazon DynamoDB 的官方开发者体验 MCP 服务器。该服务器提供 DynamoDB 专家设计指导和数据建模协助。

[!IMPORTANT] 生成式 AI 可能会出错。您应考虑审查所选 AI 模型和智能编码助手生成的所有输出。请参阅 AWS 负责任 AI 政策。

可用工具

DynamoDB MCP 服务器提供八个用于数据建模、验证、成本分析和代码生成的工具：

• dynamodb_data_modeling - 检索完整的 DynamoDB 数据建模专家提示，包含企业级设计模式、成本优化策略和多表设计理念。指导完成需求收集、访问模式分析和模式设计。

  调用示例： "使用 DynamoDB 数据建模 MCP 服务器为我的电子商务应用程序设计数据模型"

• dynamodb_data_model_validation - 通过加载 dynamodb_data_model.json、设置 DynamoDB Local、创建包含测试数据的表并执行所有定义的访问模式来验证您的 DynamoDB 数据模型。将详细的验证结果保存到 dynamodb_model_validation.json。

  调用示例： "验证我的 DynamoDB 数据模型"

• source_db_analyzer - 分析现有数据库（MySQL、PostgreSQL、SQL Server、Oracle）以提取模式结构、访问模式，并生成带时间戳的分析文件，供 dynamodb_data_modeling 使用。支持基于 RDS Data API 的访问和基于连接的 MySQL 访问。

  调用示例： "分析我的 MySQL 数据库并帮助我设计 DynamoDB 数据模型"

• generate_resources - 从 DynamoDB 数据模型 JSON 文件 (dynamodb_data_model.json) 生成各种资源。目前仅支持 cdk 资源类型。将 cdk 作为 resource_type 参数传递会生成一个用于部署 DynamoDB 表的 CDK 应用程序。该 CDK 应用程序读取 dynamodb_data_model.json 以创建具有正确配置的表。

  调用示例： "生成使用 CDK 部署我的 DynamoDB 数据模型所需的资源"

• dynamodb_data_model_schema_converter - 将您的数据模型 (dynamodb_data_model.md) 转换为结构化的 schema.json 文件，该文件表示您的 DynamoDB 表、索引、实体、字段和访问模式。这种机器可读格式用于代码生成，并可扩展用于其他目的，如文档生成或基础设施配置。自动验证模式，最多进行 8 次迭代以确保正确性。

  调用示例： "将我的数据模型转换为 schema.json 以用于代码生成"

• dynamodb_data_model_schema_validator - 验证 schema.json 文件的代码生成兼容性。检查字段类型、操作、GSI 映射、模式 ID，并提供详细的错误消息和修复建议。确保您的模式已准备好供 generate_data_access_layer 工具使用。

  调用示例： "验证位于 /path/to/schema.json 的 schema.json 文件"

• generate_data_access_layer - 从 schema.json 生成类型安全的 Python 代码，包括具有字段验证的实体类、具有 CRUD 操作的存储库类、完全实现的访问模式以及可选的使用示例。生成的代码使用 Pydantic 进行验证，使用 boto3 进行 DynamoDB 操作。

  调用示例： "从我的 schema.json 生成 Python 代码"

• compute_performances_and_costs - 根据访问模式计算 DynamoDB 容量单位 (RCU/WCU) 和月度成本。分析所有 DynamoDB 操作（GetItem、Query、Scan、PutItem、UpdateItem、DeleteItem、BatchGetItem、BatchWriteItem、TransactGetItems、TransactWriteItems），跟踪 GSI 额外写入，并计算存储成本。将综合成本报告附加到 dynamodb_data_model.md。

  调用示例： "计算我的 DynamoDB 数据模型的成本和性能"

先决条件

1. 从 Astral 或 GitHub README 安装 uv
2. 使用 uv python install 3.10 安装 Python
3. 设置具有 AWS 服务访问权限的 AWS 凭证

安装

Kiro	Cursor	VS Code

注意： 上面的安装按钮默认将 AWS_REGION 配置为 us-west-2。如果您需要不同的区域，请在安装后在 MCP 配置中更新此值。

将 MCP 服务器添加到您的配置文件（对于 Kiro，添加到 .kiro/settings/mcp.json - 请参阅 配置路径）：

{
  "mcpServers": {
    "awslabs-dynamodb-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.dynamodb-mcp-server@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Windows 安装

对于 Windows 用户，MCP 服务器配置格式略有不同：

{
  "mcpServers": {
    "awslabs-dynamodb-mcp-server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "awslabs.dynamodb-mcp-server@latest",
        "awslabs.dynamodb-mcp-server.exe"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

Docker 安装

成功 docker build -t awslabs/dynamodb-mcp-server . 后：

{
  "mcpServers": {
    "awslabs-dynamodb-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "--interactive",
        "--env",
        "FASTMCP_LOG_LEVEL=ERROR",
        "awslabs/dynamodb-mcp-server:latest"
      ],
      "env": {},
      "disabled": false,
      "autoApprove": []
    }
  }
}

数据建模

自然语言数据建模

使用 dynamodb_data_modeling 工具通过与 AI 代理的自然语言对话来设计 DynamoDB 数据模型。只需询问："使用我的 DynamoDB MCP 帮助我设计 DynamoDB 数据模型。"

该工具提供了一个结构化的工作流程，将应用程序需求转化为 DynamoDB 数据模型：

需求收集阶段：

• 通过自然语言对话捕获访问模式
• 记录实体、关系以及读/写模式
• 记录每个模式的每秒估计请求数 (RPS)
• 创建实时更新的 dynamodb_requirements.md 文件
• 识别更适合其他 AWS 服务的模式（用于文本搜索的 OpenSearch、用于分析的 Redshift）
• 标记特殊设计注意事项（例如，需要 DynamoDB Streams 和 Lambda 的大规模扇出模式）

设计阶段：

• 生成优化的表和索引设计
• 创建包含详细设计原理的 dynamodb_data_model.md
• 提供估算的月度成本
• 记录每个访问模式的支持方式
• 包含针对规模和性能的优化建议

该工具由专家工程化的上下文支持，可帮助推理模型指导您完成高级建模技术。使用具备推理能力的模型（如 Anthropic Claude 4/4.5 Sonnet、OpenAI o3 和 Google Gemini 2.5）可获得最佳效果。

数据模型验证

数据模型验证的先决条件： 要使用数据模型验证工具，您需要满足以下条件之一：

• 容器运行时：Docker、Podman、Finch 或 nerdctl，并带有正在运行的守护进程
• Java 运行时：Java JRE 17 或更新版本（设置 JAVA_HOME 或确保 java 在系统 PATH 中）

完成数据模型设计后，使用 dynamodb_data_model_validation 工具根据 DynamoDB Local 自动测试您的数据模型。验证工具通过创建迭代验证循环来闭合生成与执行之间的回路。

工作原理：

该工具自动化了传统的手动验证过程：

1. 设置：启动 DynamoDB Local 环境（Docker/Podman/Finch/nerdctl 或 Java 回退）
2. 生成测试规范：创建 dynamodb_data_model.json，列出要测试的表、示例数据和访问模式
3. 部署模式：在本地创建表、索引并插入示例数据
4. 执行测试：运行访问模式中定义的所有读写操作
5. 验证结果：检查每个访问模式是否行为正确且高效
6. 迭代优化：如果验证失败（例如，由于分区键不匹配导致查询返回不完整结果），工具会记录问题，重新生成受影响的模式并重新运行测试，直到所有模式通过

验证输出：

• dynamodb_model_validation.json：包含模式响应的详细验证结果
• validation_result.md：验证过程摘要，包含每个访问模式的通过/失败状态
• 识别诸如键结构不正确、缺少索引或查询模式效率低下等问题

源数据库分析

source_db_analyzer 工具从您现有的数据库中提取模式和访问模式，以帮助设计 DynamoDB 模型。这在从关系数据库迁移时非常有用。

该工具支持两种 MySQL 连接方法：

• 基于 RDS Data API 的访问：使用集群 ARN 的无服务器连接
• 基于连接的访问：使用主机名/端口的传统连接

支持的数据库：

• MySQL / Aurora MySQL
• PostgreSQL
• SQL Server
• Oracle

执行模式：

• 自助模式：生成 SQL 查询，自行运行，提供结果（MySQL、PostgreSQL、SQL Server、Oracle）
• 托管模式：通过 AWS RDS Data API 直接连接（仅限 MySQL）

我们建议针对非生产数据库实例运行此工具。

自助模式（MySQL、PostgreSQL、SQL Server、Oracle）

自助模式允许您在无需 AWS 连接的情况下分析任何数据库：

1. 生成查询：工具将 SQL 查询（基于所选数据库）写入文件
2. 运行查询：您对数据库执行查询
3. 提供结果：工具解析结果并生成分析

托管模式（仅限 MySQL）

托管模式允许您将工具连接到 AWS RDS Data API，以分析现有的 MySQL/Aurora 数据库，从而提取用于 DynamoDB 建模的模式和访问模式。

MySQL 集成（托管模式）的先决条件

对于基于 RDS Data API 的访问：

1. 启用了 RDS Data API 的 MySQL 集群
2. 存储在 AWS Secrets Manager 中的数据库凭证
3. 具有访问 RDS Data API 和 Secrets Manager 权限的 AWS 凭证

对于基于连接的访问：

1. 可从您的环境访问的 MySQL 服务器

2. 存储在 AWS Secrets Manager 中的数据库凭证

3. Secrets Manager 密钥必须包含一个与您的数据库主机名匹配的 host 字段（除了 username 和 password）。这确保了凭证仅用于预期的数据库主机。RDS 管理的密钥会自动包含此字段。如果您手动创建了密钥，请确保它遵循 标准结构：

   aws secretsmanager create-secret \
       --name "my-db-secret" \
       --secret-string '{
           "engine": "mysql",
           "host": "my-db.cluster-xxx.us-east-1.rds.amazonaws.com",
           "username": "<username>",
           "password": "<password>",
           "dbname": "<database name>",
           "port": 3306
       }'
   

4. 具有访问 Secrets Manager 权限的 AWS 凭证

对于两种连接方法： 4. 启用性能模式以进行访问模式分析（可选但推荐）：

• 在数据库参数组中将 performance_schema 参数设置为 1
• 更改后重启数据库实例
• 使用以下命令验证：SHOW GLOBAL VARIABLES LIKE '%performance_schema'
• 考虑调整：
  • performance_schema_digests_size - events_statements_summary_by_digest 中的最大行数
  • performance_schema_max_digest_length - 每个语句摘要的最大字节长度（默认值：1024）
• 如果没有性能模式，分析仅基于信息模式

MySQL 环境变量

添加这些环境变量以启用 MySQL 集成：

对于基于 RDS Data API 的访问：

• MYSQL_CLUSTER_ARN：MySQL 集群 ARN
• MYSQL_SECRET_ARN：包含数据库凭证的密钥的 ARN
• MYSQL_DATABASE：要分析的数据库名称
• AWS_REGION：集群所在的 AWS 区域

对于基于连接的访问：

• MYSQL_HOSTNAME：MySQL 服务器主机名或端点
• MYSQL_PORT：MySQL 服务器端口（可选，默认值：3306）
• MYSQL_SECRET_ARN：包含数据库凭证的密钥的 ARN
• MYSQL_DATABASE：要分析的数据库名称
• AWS_REGION：Secrets Manager 所在的 AWS 区域

常用选项：

• MYSQL_MAX_QUERY_RESULTS：分析输出文件中的最大行数（可选，默认值：500）

注意： 显式工具参数优先于环境变量。只应指定一种连接方法（集群 ARN 或主机名）。

使用 MySQL 的 MCP 配置

对于基于 RDS Data API 的访问：

{
  "mcpServers": {
    "awslabs-dynamodb-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.dynamodb-mcp-server@latest"],
      "env": {
        "AWS_PROFILE": "default",
        "AWS_REGION": "us-west-2",
        "FASTMCP_LOG_LEVEL": "ERROR",
        "MYSQL_CLUSTER_ARN": "arn:aws:rds:$REGION:$ACCOUNT_ID:cluster:$CLUSTER_NAME",
        "MYSQL_SECRET_ARN": "arn:aws:secretsmanager:$REGION:$ACCOUNT_ID:secret:$SECRET_NAME",
        "MYSQL_DATABASE": "<DATABASE_NAME>",
        "MYSQL_MAX_QUERY_RESULTS": "500"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

对于基于连接的访问：

{
  "mcpServers": {
    "awslabs.dynamodb-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.dynamodb-mcp-server@latest"],
      "env": {
        "AWS_PROFILE": "default",
        "AWS_REGION": "us-west-2",
        "FASTMCP_LOG_LEVEL": "ERROR",
        "MYSQL_HOSTNAME": "<MYSQL_HOST>",
        "MYSQL_PORT": "3306",
        "MYSQL_SECRET_ARN": "arn:aws:secretsmanager:$REGION:$ACCOUNT_ID:secret:$SECRET_NAME",
        "MYSQL_DATABASE": "<DATABASE_NAME>",
        "MYSQL_MAX_QUERY_RESULTS": "500"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

使用源数据库分析

1. 对您的数据库运行 source_db_analyzer（自助或托管模式）
2. 查看生成的时间戳分析文件夹（database_analysis_YYYYMMDD_HHMMSS）
3. 首先阅读 manifest.md 文件——它列出了所有分析文件和统计信息
4. 阅读所有分析文件，了解模式结构和访问模式
5. 结合 dynamodb_data_modeling 使用分析结果来设计您的 DynamoDB 模式

该工具会生成包含以下内容的 Markdown 文件：

• 模式结构（表、列、索引、外键）
• 来自 Performance Schema 的访问模式（查询模式、RPS、频率）
• 带时间戳的分析，用于跟踪随时间的变化

模式转换与代码生成

设计好 DynamoDB 数据模型后，您可以将其转换为结构化模式并生成参考 Python 代码。通过 LLM 使用 MCP 工具时，整个工作流程会自动完成——LLM 会在一次对话中引导您完成模式转换、验证和代码生成，无需手动调用工具。

对于独立使用场景，您也可以直接通过 CLI 调用这些工具，或手动编辑 schema.json 文件并按需重新生成代码。

注意： 数据模型验证（dynamodb_data_model_validation）对于代码生成是可选的。不过，如果您计划使用 usage_examples.py 在 DynamoDB Local 上测试生成的代码，建议先运行验证，因为它会自动在 DynamoDB Local 中设置表和测试数据。

将数据模型转换为模式

dynamodb_data_model_schema_converter 工具会将您可读的数据模型（dynamodb_data_model.md）转换为结构化的 JSON 模式，表示您的 DynamoDB 表、索引、实体和访问模式。这种机器可读格式支持代码生成，并可扩展用于文档或基础设施配置。

该工具会自动验证生成的模式，如果验证失败，会提供详细的错误信息和修复建议。输出会保存到带时间戳的文件夹中，以实现隔离。

模式结构：

生成的 schema.json 是一个结构化表示，包含：

• 表：一个或多个 DynamoDB 表定义，包含分区键/排序键
• GSI 定义：全局二级索引配置（可选）
• 实体：具有类型化字段的领域模型（用户、订单、产品等）
• 字段类型：string、integer、decimal、boolean、array、object、uuid
• 访问模式：带有参数定义和键模板的 Query/Scan/GetItem 操作
• 键模板：用于生成分区键和排序键的模式（例如 USER#{user_id}）

这种结构化格式可作为代码生成工具的输入。

验证模式文件

dynamodb_data_model_schema_validator 工具会验证您的 schema.json 文件，确保其格式适合代码生成。

验证检查：

• 必需部分（table_config、entities）存在
• 所有必填字段均已提供
• 字段类型有效（string、integer、decimal、boolean、array、object、uuid）
• 枚举值正确（操作类型、返回类型）
• 所有实体中的模式 ID 唯一
• GSI 名称在 gsi_list 和 gsi_mappings 之间匹配
• 模板中引用的字段存在于实体字段中
• 范围条件有效，参数数量正确
• 访问模式具有有效的操作和返回类型

安全性：

模式文件必须位于当前工作目录或其子目录中。出于安全考虑，路径遍历尝试会被阻止。

验证输出示例：

成功：

✅ Schema validation passed!

错误及建议：

❌ Schema validation failed:
  • entities.User.fields[0].type: Invalid type value 'strng'
    💡 Did you mean 'string'? Valid options: string, integer, decimal, boolean, array, object, uuid

生成数据访问层

generate_data_access_layer 工具会根据您已验证的 schema.json 文件生成类型安全的 Python 代码。

生成的代码：

• 实体类：具有字段验证和类型安全的 Pydantic 模型
• 仓库类：每个实体的 CRUD 操作（创建、读取、更新、删除）
• 访问模式：根据您的模式完全实现的查询和扫描操作
• 基础仓库：所有仓库共享的功能
• 使用示例：演示如何使用生成的类的示例代码（可选）
• 配置：用于代码质量和格式化的 ruff.toml

代码生成的先决条件：

生成的 Python 代码需要以下运行时依赖：

• pydantic>=2.0 - 用于实体验证和类型安全
• boto3>=1.38 - 用于 DynamoDB 操作

在您的项目中安装它们：

uv add pydantic boto3
# or
pip install pydantic boto3

可选的开发依赖：

用于对生成的代码进行 lint 检查和格式化：

• ruff==0.15.8 - Python linter 和格式化工具（推荐）

生成的文件结构：

generated_dal/
├── entities.py              # Pydantic entity models
├── repositories.py          # Repository classes with CRUD operations
├── base_repository.py       # Base repository functionality
├── transaction_service.py   # Cross-table transaction methods (if schema includes cross_table_access_patterns)
├── access_pattern_mapping.json  # Pattern ID to method mapping
├── usage_examples.py        # Sample usage code (if enabled)
└── ruff.toml               # Linting configuration

使用生成的代码：

生成的代码为所有访问模式提供了类型安全的实体类和仓库方法：

from generated_dal.repositories import UserRepository
from generated_dal.entities import User

# Initialize repository
repo = UserRepository(table_name="MyTable")

# Create a new user
user = User(user_id="123", username="username", name="John Doe")
repo.create(user)

# Query by access pattern
users = repo.get_user_by_username(username="username")

# Update user
user.name = "Jane Doe"
repo.update(user)

使用 ruff 对生成的代码进行 lint 检查和格式化：

ruff check generated_dal/        # Check for issues
ruff check --fix generated_dal/  # Auto-fix issues
ruff format generated_dal/       # Format code