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)을 DynamoDB 테이블, 인덱스, 엔터티, 필드 및 액세스 패턴을 나타내는 구조화된 schema.json 파일로 변환합니다. 이 기계 판독 가능 형식은 코드 생성에 사용되며 문서 생성이나 인프라 프로비저닝과 같은 다른 목적으로 확장할 수 있습니다. 정확성을 보장하기 위해 최대 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에서 필드 유효성 검사가 포함된 엔터티 클래스, CRUD 작업이 포함된 리포지토리 클래스, 완전히 구현된 액세스 패턴 및 선택적 사용 예제를 포함한 유형 안전 Python 코드를 생성합니다. 생성된 코드는 유효성 검사에 Pydantic을 사용하고 DynamoDB 작업에 boto3를 사용합니다.

  호출 예시: "내 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 활성화(선택 사항이지만 권장):

• DB 파라미터 그룹에서 performance_schema 매개변수를 1로 설정
• 변경 후 DB 인스턴스 재부팅
• 확인: SHOW GLOBAL VARIABLES LIKE '%performance_schema'
• 튜닝 고려 사항:
  • performance_schema_digests_size - events_statements_summary_by_digest의 최대 행 수
  • performance_schema_max_digest_length - 명령문 다이제스트당 최대 바이트 길이(기본값: 1024)
• Performance 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)은 코드 생성 시 선택 사항입니다. 그러나 생성된 코드를 DynamoDB Local에서 usage_examples.py을(를) 사용하여 테스트할 계획이라면, 검증을 먼저 실행하는 것이 좋습니다. 검증을 실행하면 DynamoDB Local에 테이블과 테스트 데이터가 자동으로 설정되기 때문입니다.

데이터 모델을 스키마로 변환

dynamodb_data_model_schema_converter 도구는 사람이 읽을 수 있는 데이터 모델(dynamodb_data_model.md)을 DynamoDB 테이블, 인덱스, 엔티티, 액세스 패턴을 나타내는 구조화된 JSON 스키마로 변환합니다. 이 기계 판독 가능 형식은 코드 생성을 가능하게 하며 문서화 또는 인프라 프로비저닝을 위해 확장될 수 있습니다.

이 도구는 생성된 스키마를 자동으로 검증하여 검증 실패 시 상세한 오류 메시지와 수정 제안을 제공합니다. 출력은 격리를 위해 타임스탬프가 지정된 폴더에 저장됩니다.

스키마 구조:

생성된 schema.json은 다음을 포함하는 구조화된 표현입니다:

• 테이블: 파티션/정렬 키가 있는 하나 이상의 DynamoDB 테이블 정의
• GSI 정의: 글로벌 보조 인덱스 구성 (선택 사항)
• 엔티티: 유형이 지정된 필드가 있는 도메인 모델 (User, Order, Product 등)
• 필드 유형: 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_list와 gsi_mappings 간 GSI 이름 일치
• 템플릿에서 참조된 필드가 엔티티 필드에 존재하는지 여부
• 올바른 매개변수 개수를 가진 유효한 범위 조건
• 유효한 작업 및 반환 유형을 가진 액세스 패턴

보안:

스키마 파일은 현재 작업 디렉터리 또는 하위 디렉터리 내에 있어야 합니다. 보안을 위해 경로 탐색 시도는 차단됩니다.

검증 출력 예시:

성공:

✅ 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

선택적 개발 종속성:

생성된 코드의 린팅 및 포맷팅 용도:

• ruff==0.15.8 - Python 린터 및 포맷터 (권장)

생성된 파일 구조:

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를 사용한 생성된 코드의 린팅 및 포맷팅:

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