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 參數會產生 CDK 應用程式來部署 DynamoDB 資料表。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 以進行存取模式分析（選用但建議）：

• 在您的資料庫參數群組中將 performance_schema 參數設為 1
• 變更後重新啟動資料庫執行個體
• 使用以下指令驗證：SHOW GLOBAL VARIABLES LIKE '%performance_schema'
• 考慮調整：
  • performance_schema_digests_size - events_statements_summary_by_digest 中的最大資料列數
  • performance_schema_max_digest_length - 每個陳述式摘要的最大位元組長度（預設：1024）
• 若無 Performance Schema，分析將僅基於 information schema

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
• 存取模式：具有參數定義和鍵值範本的查詢/掃描/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