AWS DynamoDB MCP Server

oficial

The official developer experience MCP Server for Amazon DynamoDB. This server provides DynamoDB expert design guidance and data modeling assistance.

GitHub
9.4k

Documentación

AWS DynamoDB MCP Server

El servidor MCP oficial de experiencia de desarrollo para Amazon DynamoDB. Este servidor proporciona orientación experta en diseño de DynamoDB y asistencia en modelado de datos.

[!IMPORTANT] La IA generativa puede cometer errores. Debe considerar revisar todo el resultado generado por su modelo de IA y asistente de codificación agentiva elegidos. Consulte la Política de IA Responsable de AWS.

Herramientas Disponibles

El servidor MCP de DynamoDB proporciona ocho herramientas para modelado de datos, validación, análisis de costos y generación de código:

  • dynamodb_data_modeling - Recupera el prompt completo del Experto en Modelado de Datos de DynamoDB con patrones de diseño de nivel empresarial, estrategias de optimización de costos y filosofía de diseño multi-tabla. Guía a través de la recopilación de requisitos, análisis de patrones de acceso y diseño de esquemas.

    Ejemplo de invocación: "Diseña un modelo de datos para mi aplicación de comercio electrónico usando el servidor MCP de modelado de datos de DynamoDB"

  • dynamodb_data_model_validation - Valida su modelo de datos de DynamoDB cargando dynamodb_data_model.json, configurando DynamoDB Local, creando tablas con datos de prueba y ejecutando todos los patrones de acceso definidos. Guarda los resultados detallados de la validación en dynamodb_model_validation.json.

    Ejemplo de invocación: "Valida mi modelo de datos de DynamoDB"

  • source_db_analyzer - Analiza bases de datos existentes (MySQL, PostgreSQL, SQL Server, Oracle) para extraer la estructura del esquema, patrones de acceso y genera archivos de análisis con marca de tiempo para usar con dynamodb_data_modeling. Soporta acceso basado en RDS Data API y acceso basado en conexión para MySQL.

    Ejemplo de invocación: "Analiza mi base de datos MySQL y ayúdame a diseñar un modelo de datos de DynamoDB"

  • generate_resources - Genera varios recursos desde el archivo JSON del modelo de datos de DynamoDB (dynamodb_data_model.json). Actualmente solo se soporta el tipo de recurso cdk. Pasar cdk como parámetro resource_type genera una aplicación CDK para desplegar tablas de DynamoDB. La aplicación CDK lee dynamodb_data_model.json para crear tablas con la configuración adecuada.

    Ejemplo de invocación: "Genera los recursos para desplegar mi modelo de datos de DynamoDB usando CDK"

  • dynamodb_data_model_schema_converter - Convierte su modelo de datos (dynamodb_data_model.md) en un archivo schema.json estructurado que representa sus tablas, índices, entidades, campos y patrones de acceso de DynamoDB. Este formato legible por máquina se usa para generación de código y puede extenderse para otros propósitos como generación de documentación o aprovisionamiento de infraestructura. Valida automáticamente el esquema con hasta 8 iteraciones para asegurar la corrección.

    Ejemplo de invocación: "Convierte mi modelo de datos a schema.json para generación de código"

  • dynamodb_data_model_schema_validator - Valida archivos schema.json para compatibilidad con generación de código. Verifica tipos de campo, operaciones, mapeos GSI, IDs de patrón y proporciona mensajes de error detallados con sugerencias de corrección. Asegura que su esquema esté listo para la herramienta generate_data_access_layer.

    Ejemplo de invocación: "Valida mi archivo schema.json en /ruta/a/schema.json"

  • generate_data_access_layer - Genera código Python con seguridad de tipos desde schema.json incluyendo clases de entidad con validación de campos, clases de repositorio con operaciones CRUD, patrones de acceso completamente implementados y ejemplos de uso opcionales. El código generado usa Pydantic para validación y boto3 para operaciones de DynamoDB.

    Ejemplo de invocación: "Genera código Python desde mi schema.json"

  • compute_performances_and_costs - Calcula unidades de capacidad de DynamoDB (RCU/WCU) y costos mensuales a partir de patrones de acceso. Analiza todas las operaciones de DynamoDB (GetItem, Query, Scan, PutItem, UpdateItem, DeleteItem, BatchGetItem, BatchWriteItem, TransactGetItems, TransactWriteItems), rastrea escrituras adicionales de GSI y calcula costos de almacenamiento. Agrega un informe de costos completo a dynamodb_data_model.md.

    Ejemplo de invocación: "Calcula el costo y rendimiento para mi modelo de datos de DynamoDB"

Prerrequisitos

  1. Instale uv desde Astral o el README de GitHub
  2. Instale Python usando uv python install 3.10
  3. Configure credenciales de AWS con acceso a los servicios de AWS

Instalación

KiroCursorVS Code
KiroCursorVS Code

Nota: Los botones de instalación anteriores configuran AWS_REGION a us-west-2 por defecto. Actualice este valor en su configuración MCP después de la instalación si necesita una región diferente.

Agregue el servidor MCP a su archivo de configuración (para Kiro agregue a .kiro/settings/mcp.json - vea ruta de configuración):

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

Instalación en Windows

Para usuarios de Windows, el formato de configuración del servidor MCP es ligeramente diferente:

{
  "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"
      }
    }
  }
}

Instalación con Docker

Después de un docker build -t awslabs/dynamodb-mcp-server . exitoso:

{
  "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": []
    }
  }
}

Modelado de Datos

Modelado de Datos en Lenguaje Natural

Use la herramienta dynamodb_data_modeling para diseñar modelos de datos de DynamoDB a través de conversación en lenguaje natural con su agente de IA. Simplemente pregunte: "usa mi MCP de DynamoDB para ayudarme a diseñar un modelo de datos de DynamoDB."

La herramienta proporciona un flujo de trabajo estructurado que traduce los requisitos de la aplicación en modelos de datos de DynamoDB:

Fase de Recopilación de Requisitos:

  • Captura patrones de acceso a través de conversación en lenguaje natural
  • Documenta entidades, relaciones y patrones de lectura/escritura
  • Registra solicitudes estimadas por segundo (RPS) para cada patrón
  • Crea el archivo dynamodb_requirements.md que se actualiza en tiempo real
  • Identifica patrones más adecuados para otros servicios de AWS (OpenSearch para búsqueda de texto, Redshift para analítica)
  • Señala consideraciones especiales de diseño (ej., patrones masivos de fan-out que requieren DynamoDB Streams y Lambda)

Fase de Diseño:

  • Genera diseños optimizados de tablas e índices
  • Crea dynamodb_data_model.md con justificación detallada del diseño
  • Proporciona costos mensuales estimados
  • Documenta cómo se soporta cada patrón de acceso
  • Incluye recomendaciones de optimización para escala y rendimiento

La herramienta está respaldada por contexto diseñado por expertos que ayuda a los modelos de razonamiento a guiarlo a través de técnicas avanzadas de modelado. Los mejores resultados se obtienen con modelos con capacidad de razonamiento como Anthropic Claude 4/4.5 Sonnet, OpenAI o3 y Google Gemini 2.5.

Validación del Modelo de Datos

Prerrequisitos para la Validación del Modelo de Datos: Para usar la herramienta de validación del modelo de datos, necesita uno de los siguientes:

  • Entorno de ejecución de contenedores: Docker, Podman, Finch o nerdctl con un daemon en ejecución
  • Entorno de ejecución Java: Java JRE versión 17 o más reciente (configure JAVA_HOME o asegúrese de que java esté en su PATH del sistema)

Después de completar el diseño de su modelo de datos, use la herramienta dynamodb_data_model_validation para probar automáticamente su modelo de datos contra DynamoDB Local. La herramienta de validación cierra el ciclo entre generación y ejecución creando un ciclo de validación iterativo.

Cómo Funciona:

La herramienta automatiza el proceso tradicional de validación manual:

  1. Configuración: Inicia el entorno de DynamoDB Local (Docker/Podman/Finch/nerdctl o alternativa Java)
  2. Generar Especificación de Prueba: Crea dynamodb_data_model.json listando tablas, datos de muestra y patrones de acceso a probar
  3. Desplegar Esquema: Crea tablas, índices e inserta datos de muestra localmente
  4. Ejecutar Pruebas: Ejecuta todas las operaciones de lectura y escritura definidas en sus patrones de acceso
  5. Validar Resultados: Verifica que cada patrón de acceso se comporte correcta y eficientemente
  6. Refinamiento Iterativo: Si la validación falla (ej., la consulta devuelve resultados incompletos debido a una clave de partición desalineada), la herramienta registra el problema, regenera el esquema afectado y vuelve a ejecutar las pruebas hasta que todos los patrones pasen

Salida de la Validación:

  • dynamodb_model_validation.json: Resultados detallados de validación con respuestas de patrones
  • validation_result.md: Resumen del proceso de validación con estado aprobado/fallido para cada patrón de acceso
  • Identifica problemas como estructuras de clave incorrectas, índices faltantes o patrones de consulta ineficientes

Análisis de Base de Datos de Origen

La herramienta source_db_analyzer extrae el esquema y los patrones de acceso de su base de datos existente para ayudar a diseñar su modelo de DynamoDB. Esto es útil al migrar desde bases de datos relacionales.

La herramienta soporta dos métodos de conexión para MySQL:

  • Acceso basado en RDS Data API: Conexión sin servidor usando el ARN del clúster
  • Acceso basado en conexión: Conexión tradicional usando nombre de host/puerto

Bases de Datos Soportadas:

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

Modos de Ejecución:

  • Modo Autoservicio: Genere consultas SQL, ejecútelas usted mismo, proporcione los resultados (MySQL, PostgreSQL, SQL Server, Oracle)
  • Modo Gestionado: Conexión directa a través de AWS RDS Data API (solo MySQL)

Recomendamos ejecutar esta herramienta contra una instancia de base de datos no productiva.

Modo Autoservicio (MySQL, PostgreSQL, SQL Server, Oracle)

El modo autoservicio le permite analizar cualquier base de datos sin conectividad a AWS:

  1. Generar Consultas: La herramienta escribe consultas SQL (basadas en la base de datos seleccionada) en un archivo
  2. Ejecutar Consultas: Usted ejecuta las consultas contra su base de datos
  3. Proporcionar Resultados: La herramienta analiza los resultados y genera el análisis

Modo Gestionado (solo MySQL)

El modo gestionado le permite conectar la herramienta a AWS RDS Data API para analizar bases de datos MySQL/Aurora existentes y extraer esquemas y patrones de acceso para el modelado de DynamoDB.

Prerrequisitos para Integración MySQL (Modo Gestionado)

Para acceso basado en RDS Data API:

  1. Clúster MySQL con RDS Data API habilitado
  2. Credenciales de base de datos almacenadas en AWS Secrets Manager
  3. Credenciales de AWS con permisos para acceder a RDS Data API y Secrets Manager

Para acceso basado en conexión:

  1. Servidor MySQL accesible desde su entorno

  2. Credenciales de base de datos almacenadas en AWS Secrets Manager

  3. El secreto de Secrets Manager debe contener un campo host que coincida con el nombre de host de su base de datos (además de username y password). Esto asegura que las credenciales solo se usen con el host de base de datos previsto. Los secretos gestionados por RDS incluyen este campo automáticamente. Si creó su secreto manualmente, asegúrese de que siga la estructura estándar:

    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. Credenciales de AWS con permisos para acceder a Secrets Manager

Para ambos métodos de conexión: 4. Habilite Performance Schema para análisis de patrones de acceso (opcional pero recomendado):

  • Establezca el parámetro performance_schema a 1 en su grupo de parámetros de DB
  • Reinicie la instancia de DB después de los cambios
  • Verifique con: SHOW GLOBAL VARIABLES LIKE '%performance_schema'
  • Considere ajustar:
    • performance_schema_digests_size - Máximo de filas en events_statements_summary_by_digest
    • performance_schema_max_digest_length - Longitud máxima en bytes por resumen de sentencia (predeterminado: 1024)
  • Sin Performance Schema, el análisis se basa solo en el esquema de información

Variables de Entorno para MySQL

Agregue estas variables de entorno para habilitar la integración con MySQL:

Para acceso basado en RDS Data API:

  • MYSQL_CLUSTER_ARN: ARN del clúster MySQL
  • MYSQL_SECRET_ARN: ARN del secreto que contiene las credenciales de la base de datos
  • MYSQL_DATABASE: Nombre de la base de datos a analizar
  • AWS_REGION: Región de AWS del clúster

Para acceso basado en conexión:

  • MYSQL_HOSTNAME: Nombre de host o endpoint del servidor MySQL
  • MYSQL_PORT: Puerto del servidor MySQL (opcional, predeterminado: 3306)
  • MYSQL_SECRET_ARN: ARN del secreto que contiene las credenciales de la base de datos
  • MYSQL_DATABASE: Nombre de la base de datos a analizar
  • AWS_REGION: Región de AWS donde se encuentra Secrets Manager

Opciones comunes:

  • MYSQL_MAX_QUERY_RESULTS: Máximo de filas en archivos de salida de análisis (opcional, predeterminado: 500)

Nota: Los parámetros explícitos de la herramienta tienen prioridad sobre las variables de entorno. Solo se debe especificar un método de conexión (ARN del clúster o nombre de host).

Configuración MCP con MySQL

Para acceso basado en 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": []
    }
  }
}

Para acceso basado en conexión:

{
  "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": []
    }
  }
}

Uso del Análisis de Base de Datos de Origen

  1. Ejecute source_db_analyzer contra su base de datos (modo autogestionado o administrado)
  2. Revise la carpeta de análisis con marca de tiempo generada (database_analysis_AAAAMMDD_HHMMSS)
  3. Lea primero el archivo manifest.md: enumera todos los archivos de análisis y estadísticas
  4. Lea todos los archivos de análisis para comprender la estructura del esquema y los patrones de acceso
  5. Utilice el análisis con dynamodb_data_modeling para diseñar su esquema de DynamoDB

La herramienta genera archivos Markdown con:

  • Estructura del esquema (tablas, columnas, índices, claves foráneas)
  • Patrones de acceso del Esquema de Rendimiento (patrones de consulta, RPS, frecuencias)
  • Análisis con marca de tiempo para rastrear cambios a lo largo del tiempo

Conversión de Esquema y Generación de Código

Después de diseñar su modelo de datos de DynamoDB, puede convertirlo a un esquema estructurado y generar código Python de referencia. Al usar las herramientas MCP a través de un LLM, todo este flujo de trabajo ocurre automáticamente: el LLM lo guía a través de la conversión del esquema, validación y generación de código en una sola conversación sin requerir la invocación manual de herramientas.

Para uso independiente, también puede invocar estas herramientas directamente mediante CLI o editar manualmente archivos schema.json y regenerar el código según sea necesario.

Nota: La validación del modelo de datos (dynamodb_data_model_validation) es opcional para la generación de código. Sin embargo, si planea probar el código generado con usage_examples.py contra DynamoDB Local, se recomienda ejecutar primero la validación, ya que configura automáticamente las tablas y los datos de prueba en DynamoDB Local.

Conversión del Modelo de Datos a Esquema

La herramienta dynamodb_data_model_schema_converter convierte su modelo de datos legible por humanos (dynamodb_data_model.md) en un esquema JSON estructurado que representa sus tablas, índices, entidades y patrones de acceso de DynamoDB. Este formato legible por máquina permite la generación de código y puede extenderse para documentación o aprovisionamiento de infraestructura.

La herramienta valida automáticamente el esquema generado, proporcionando mensajes de error detallados y sugerencias de corrección si la validación falla. La salida se guarda en una carpeta con marca de tiempo para aislamiento.

Estructura del Esquema:

El schema.json generado es una representación estructurada que contiene:

  • Tablas: Una o más definiciones de tablas de DynamoDB con claves de partición/ordenación
  • Definiciones de GSI: Configuraciones de Índices Secundarios Globales (opcional)
  • Entidades: Modelos de dominio (Usuario, Pedido, Producto, etc.) con campos tipados
  • Tipos de Campo: string, integer, decimal, boolean, array, object, uuid
  • Patrones de Acceso: Operaciones Query/Scan/GetItem con definiciones de parámetros y plantillas de clave
  • Plantillas de Clave: Patrones para generar claves de partición y ordenación (ej., USER#{user_id})

Este formato estructurado sirve como entrada para las herramientas de generación de código.

Validación de Archivos de Esquema

La herramienta dynamodb_data_model_schema_validator valida su archivo schema.json para asegurar que esté correctamente formateado para la generación de código.

Verificaciones de Validación:

  • Existen las secciones requeridas (table_config, entities)
  • Todos los campos requeridos están presentes
  • Los tipos de campo son válidos (string, integer, decimal, boolean, array, object, uuid)
  • Los valores de enumeración son correctos (tipos de operación, tipos de retorno)
  • Los IDs de patrón son únicos en todas las entidades
  • Los nombres de GSI coinciden entre gsi_list y gsi_mappings
  • Los campos referenciados en las plantillas existen en los campos de la entidad
  • Las condiciones de rango son válidas con el número correcto de parámetros
  • Los patrones de acceso tienen operaciones y tipos de retorno válidos

Seguridad:

Los archivos de esquema deben estar dentro del directorio de trabajo actual o subdirectorios. Los intentos de path traversal se bloquean por seguridad.

Ejemplos de Salida de Validación:

Éxito:

✅ Schema validation passed!

Error con sugerencias:

❌ 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

Generación de la Capa de Acceso a Datos

La herramienta generate_data_access_layer genera código Python con seguridad de tipos a partir de su archivo schema.json validado.

Código Generado:

  • Clases de Entidad: Modelos Pydantic con validación de campos y seguridad de tipos
  • Clases de Repositorio: Operaciones CRUD (crear, leer, actualizar, eliminar) para cada entidad
  • Patrones de Acceso: Operaciones de consulta y escaneo completamente implementadas desde su esquema
  • Repositorio Base: Funcionalidad compartida para todos los repositorios
  • Ejemplos de Uso: Código de muestra que demuestra cómo usar las clases generadas (opcional)
  • Configuración: ruff.toml para calidad y formato de código

Prerrequisitos para la Generación de Código:

El código Python generado requiere estas dependencias en tiempo de ejecución:

  • pydantic>=2.0 - Para validación de entidades y seguridad de tipos
  • boto3>=1.38 - Para operaciones de DynamoDB

Instálelas en su proyecto:

uv add pydantic boto3
# or
pip install pydantic boto3

Dependencias de Desarrollo Opcionales:

Para linting y formateo del código generado:

  • ruff==0.15.8 - Linter y formateador de Python (recomendado)

Estructura de Archivos Generada:

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

Uso del Código Generado:

El código generado proporciona clases de entidad con seguridad de tipos y métodos de repositorio para todos sus patrones de acceso:

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)

Para linting y formateo del código generado con ruff:

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