AWS DynamoDB MCP Server

AWS DynamoDB MCP Server

O servidor MCP oficial de experiência do desenvolvedor para Amazon DynamoDB. Este servidor fornece orientação especializada em design do DynamoDB e assistência em modelagem de dados.

[!IMPORTANT] A IA generativa pode cometer erros. Você deve considerar revisar todo o resultado gerado pelo seu modelo de IA e assistente de codificação agentiva escolhidos. Consulte a Política de IA Responsável da AWS.

Ferramentas Disponíveis

O servidor MCP do DynamoDB fornece oito ferramentas para modelagem de dados, validação, análise de custos e geração de código:

• dynamodb_data_modeling - Recupera o prompt completo do Especialista em Modelagem de Dados do DynamoDB com padrões de design de nível empresarial, estratégias de otimização de custos e filosofia de design multi-tabela. Orienta na coleta de requisitos, análise de padrões de acesso e design de esquema.

  Exemplo de invocação: "Projete um modelo de dados para minha aplicação de e-commerce usando o servidor MCP de modelagem de dados do DynamoDB"

• dynamodb_data_model_validation - Valida seu modelo de dados do DynamoDB carregando dynamodb_data_model.json, configurando o DynamoDB Local, criando tabelas com dados de teste e executando todos os padrões de acesso definidos. Salva resultados detalhados da validação em dynamodb_model_validation.json.

  Exemplo de invocação: "Valide meu modelo de dados do DynamoDB"

• source_db_analyzer - Analisa bancos de dados existentes (MySQL, PostgreSQL, SQL Server, Oracle) para extrair a estrutura do esquema, padrões de acesso e gera arquivos de análise com timestamp para uso com dynamodb_data_modeling. Suporta acesso baseado em RDS Data API e acesso baseado em conexão para MySQL.

  Exemplo de invocação: "Analise meu banco de dados MySQL e me ajude a projetar um modelo de dados do DynamoDB"

• generate_resources - Gera vários recursos a partir do arquivo JSON do modelo de dados do DynamoDB (dynamodb_data_model.json). Atualmente, apenas o tipo de recurso cdk é suportado. Passar cdk como parâmetro resource_type gera um aplicativo CDK para implantar tabelas do DynamoDB. O aplicativo CDK lê o dynamodb_data_model.json para criar tabelas com a configuração adequada.

  Exemplo de invocação: "Gere os recursos para implantar meu modelo de dados do DynamoDB usando CDK"

• dynamodb_data_model_schema_converter - Converte seu modelo de dados (dynamodb_data_model.md) em um arquivo schema.json estruturado representando suas tabelas, índices, entidades, campos e padrões de acesso do DynamoDB. Este formato legível por máquina é usado para geração de código e pode ser estendido para outros fins, como geração de documentação ou provisionamento de infraestrutura. Valida automaticamente o esquema com até 8 iterações para garantir a correção.

  Exemplo de invocação: "Converta meu modelo de dados para schema.json para geração de código"

• dynamodb_data_model_schema_validator - Valida arquivos schema.json para compatibilidade com geração de código. Verifica tipos de campo, operações, mapeamentos de GSI, IDs de padrão e fornece mensagens de erro detalhadas com sugestões de correção. Garante que seu esquema esteja pronto para a ferramenta generate_data_access_layer.

  Exemplo de invocação: "Valide meu arquivo schema.json em /caminho/para/schema.json"

• generate_data_access_layer - Gera código Python com segurança de tipos a partir do schema.json, incluindo classes de entidade com validação de campo, classes de repositório com operações CRUD, padrões de acesso totalmente implementados e exemplos de uso opcionais. O código gerado usa Pydantic para validação e boto3 para operações do DynamoDB.

  Exemplo de invocação: "Gere código Python a partir do meu schema.json"

• compute_performances_and_costs - Calcula unidades de capacidade do DynamoDB (RCU/WCU) e custos mensais a partir dos padrões de acesso. Analisa todas as operações do DynamoDB (GetItem, Query, Scan, PutItem, UpdateItem, DeleteItem, BatchGetItem, BatchWriteItem, TransactGetItems, TransactWriteItems), rastreia gravações adicionais de GSI e calcula custos de armazenamento. Anexa um relatório de custos abrangente ao dynamodb_data_model.md.

  Exemplo de invocação: "Calcule o custo e o desempenho para meu modelo de dados do DynamoDB"

Pré-requisitos

1. Instale o uv da Astral ou do README do GitHub
2. Instale o Python usando uv python install 3.10
3. Configure credenciais AWS com acesso aos serviços AWS

Instalação

Kiro	Cursor	VS Code

Nota: Os botões de instalação acima configuram AWS_REGION para us-west-2 por padrão. Atualize este valor na sua configuração MCP após a instalação se precisar de uma região diferente.

Adicione o servidor MCP ao seu arquivo de configuração (para Kiro adicione ao .kiro/settings/mcp.json - veja o caminho de configuração):

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

Instalação no Windows

Para usuários do Windows, o formato de configuração do servidor MCP é ligeiramente 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"
      }
    }
  }
}

Instalação com Docker

Após um docker build -t awslabs/dynamodb-mcp-server . bem-sucedido:

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

Modelagem de Dados

Modelagem de Dados em Linguagem Natural

Use a ferramenta dynamodb_data_modeling para projetar modelos de dados do DynamoDB através de conversa em linguagem natural com seu agente de IA. Basta perguntar: "use meu MCP do DynamoDB para me ajudar a projetar um modelo de dados do DynamoDB."

A ferramenta fornece um fluxo de trabalho estruturado que traduz requisitos da aplicação em modelos de dados do DynamoDB:

Fase de Coleta de Requisitos:

• Captura padrões de acesso através de conversa em linguagem natural
• Documenta entidades, relacionamentos e padrões de leitura/gravação
• Registra requisições estimadas por segundo (RPS) para cada padrão
• Cria o arquivo dynamodb_requirements.md que é atualizado em tempo real
• Identifica padrões mais adequados para outros serviços AWS (OpenSearch para busca textual, Redshift para análises)
• Sinaliza considerações especiais de design (ex.: padrões de fan-out massivo que exigem DynamoDB Streams e Lambda)

Fase de Design:

• Gera designs otimizados de tabelas e índices
• Cria dynamodb_data_model.md com justificativa detalhada do design
• Fornece custos mensais estimados
• Documenta como cada padrão de acesso é suportado
• Inclui recomendações de otimização para escala e desempenho

A ferramenta é apoiada por contexto projetado por especialistas que ajuda modelos de raciocínio a guiá-lo através de técnicas avançadas de modelagem. Os melhores resultados são obtidos com modelos capazes de raciocínio, como Anthropic Claude 4/4.5 Sonnet, OpenAI o3 e Google Gemini 2.5.

Validação do Modelo de Dados

Pré-requisitos para Validação do Modelo de Dados: Para usar a ferramenta de validação do modelo de dados, você precisa de um dos seguintes:

• Runtime de Contêiner: Docker, Podman, Finch ou nerdctl com um daemon em execução
• Runtime Java: Java JRE versão 17 ou mais recente (defina JAVA_HOME ou garanta que java esteja no PATH do seu sistema)

Após concluir o design do seu modelo de dados, use a ferramenta dynamodb_data_model_validation para testar automaticamente seu modelo de dados no DynamoDB Local. A ferramenta de validação fecha o ciclo entre geração e execução, criando um ciclo de validação iterativo.

Como Funciona:

A ferramenta automatiza o processo tradicional de validação manual:

1. Configuração: Inicia o ambiente DynamoDB Local (Docker/Podman/Finch/nerdctl ou fallback Java)
2. Gerar Especificação de Teste: Cria dynamodb_data_model.json listando tabelas, dados de amostra e padrões de acesso a testar
3. Implantar Esquema: Cria tabelas, índices e insere dados de amostra localmente
4. Executar Testes: Executa todas as operações de leitura e gravação definidas nos seus padrões de acesso
5. Validar Resultados: Verifica se cada padrão de acesso se comporta corretamente e de forma eficiente
6. Refinamento Iterativo: Se a validação falhar (ex.: consulta retorna resultados incompletos devido à chave de partição desalinhada), a ferramenta registra o problema, regenera o esquema afetado e reexecuta os testes até que todos os padrões passem

Saída da Validação:

• dynamodb_model_validation.json: Resultados detalhados da validação com respostas dos padrões
• validation_result.md: Resumo do processo de validação com status de aprovação/reprovação para cada padrão de acesso
• Identifica problemas como estruturas de chave incorretas, índices ausentes ou padrões de consulta ineficientes

Análise de Banco de Dados de Origem

A ferramenta source_db_analyzer extrai esquema e padrões de acesso do seu banco de dados existente para ajudar a projetar seu modelo do DynamoDB. Isso é útil ao migrar de bancos de dados relacionais.

A ferramenta suporta dois métodos de conexão para MySQL:

• Acesso baseado em RDS Data API: Conexão serverless usando ARN do cluster
• Acesso baseado em conexão: Conexão tradicional usando hostname/porta

Bancos de Dados Suportados:

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

Modos de Execução:

• Modo Autosserviço: Gera consultas SQL, execute-as você mesmo, forneça os resultados (MySQL, PostgreSQL, SQL Server, Oracle)
• Modo Gerenciado: Conexão direta via AWS RDS Data API (somente MySQL)

Recomendamos executar esta ferramenta em uma instância de banco de dados não produtiva.

Modo Autosserviço (MySQL, PostgreSQL, SQL Server, Oracle)

O modo autosserviço permite analisar qualquer banco de dados sem conectividade AWS:

1. Gerar Consultas: A ferramenta grava consultas SQL (com base no banco de dados selecionado) em um arquivo
2. Executar Consultas: Você executa as consultas no seu banco de dados
3. Fornecer Resultados: A ferramenta analisa os resultados e gera a análise

Modo Gerenciado (somente MySQL)

O modo gerenciado permite conectar a ferramenta ao AWS RDS Data API para analisar bancos de dados MySQL/Aurora existentes e extrair esquema e padrões de acesso para modelagem no DynamoDB.

Pré-requisitos para Integração MySQL (Modo Gerenciado)

Para acesso baseado em RDS Data API:

1. Cluster MySQL com RDS Data API habilitado
2. Credenciais do banco de dados armazenadas no AWS Secrets Manager
3. Credenciais AWS com permissões para acessar RDS Data API e Secrets Manager

Para acesso baseado em conexão:

1. Servidor MySQL acessível a partir do seu ambiente

2. Credenciais do banco de dados armazenadas no AWS Secrets Manager

3. O segredo do Secrets Manager deve conter um campo host correspondente ao hostname do seu banco de dados (além de username e password). Isso garante que as credenciais sejam usadas apenas com o host de banco de dados pretendido. Segredos gerenciados pelo RDS incluem este campo automaticamente. Se você criou seu segredo manualmente, garanta que ele siga a estrutura padrão:

   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. Credenciais AWS com permissões para acessar o Secrets Manager

Para ambos os métodos de conexão: 4. Habilite o Performance Schema para análise de padrões de acesso (opcional, mas recomendado):

• Defina o parâmetro performance_schema como 1 no seu grupo de parâmetros do DB
• Reinicie a instância do DB após as alterações
• Verifique com: SHOW GLOBAL VARIABLES LIKE '%performance_schema'
• Considere ajustar:
  • performance_schema_digests_size - Máximo de linhas em events_statements_summary_by_digest
  • performance_schema_max_digest_length - Comprimento máximo em bytes por resumo de declaração (padrão: 1024)
• Sem o Performance Schema, a análise é baseada apenas no information schema

Variáveis de Ambiente do MySQL

Adicione estas variáveis de ambiente para habilitar a integração MySQL:

Para acesso baseado em RDS Data API:

• MYSQL_CLUSTER_ARN: ARN do cluster MySQL
• MYSQL_SECRET_ARN: ARN do segredo contendo as credenciais do banco de dados
• MYSQL_DATABASE: Nome do banco de dados a analisar
• AWS_REGION: Região AWS do cluster

Para acesso baseado em conexão:

• MYSQL_HOSTNAME: Hostname ou endpoint do servidor MySQL
• MYSQL_PORT: Porta do servidor MySQL (opcional, padrão: 3306)
• MYSQL_SECRET_ARN: ARN do segredo contendo as credenciais do banco de dados
• MYSQL_DATABASE: Nome do banco de dados a analisar
• AWS_REGION: Região AWS onde o Secrets Manager está localizado

Opções comuns:

• MYSQL_MAX_QUERY_RESULTS: Máximo de linhas nos arquivos de saída da análise (opcional, padrão: 500)

Nota: Parâmetros explícitos da ferramenta têm precedência sobre variáveis de ambiente. Apenas um método de conexão (ARN do cluster ou hostname) deve ser especificado.

Configuração MCP com MySQL

Para acesso baseado em 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 acesso baseado em conexão:

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

Usando Análise de Banco de Dados de Origem

1. Execute source_db_analyzer no seu Banco de Dados (modo Self-service ou Managed)
2. Revise a pasta de análise com timestamp gerada (database_analysis_YYYYMMDD_HHMMSS)
3. Leia primeiro o arquivo manifest.md - ele lista todos os arquivos de análise e estatísticas
4. Leia todos os arquivos de análise para entender a estrutura do esquema e os padrões de acesso
5. Use a análise com dynamodb_data_modeling para projetar seu esquema do DynamoDB

A ferramenta gera arquivos Markdown com:

• Estrutura do esquema (tabelas, colunas, índices, chaves estrangeiras)
• Padrões de acesso do Performance Schema (padrões de consulta, RPS, frequências)
• Análise com timestamp para rastrear mudanças ao longo do tempo

Conversão de Esquema e Geração de Código

Após projetar seu modelo de dados do DynamoDB, você pode convertê-lo em um esquema estruturado e gerar código Python de referência. Ao usar as ferramentas MCP através de um LLM, todo esse fluxo de trabalho acontece automaticamente - o LLM guia você pela conversão de esquema, validação e geração de código em uma única conversa, sem necessidade de invocação manual de ferramentas.

Para uso independente, você também pode invocar essas ferramentas diretamente via CLI ou editar manualmente os arquivos schema.json e regenerar o código conforme necessário.

Nota: A validação do modelo de dados (dynamodb_data_model_validation) é opcional para a geração de código. No entanto, se você planeja testar o código gerado com usage_examples.py no DynamoDB Local, é recomendável executar a validação primeiro, pois ela configura automaticamente as tabelas e os dados de teste no DynamoDB Local.

Convertendo Modelo de Dados em Esquema

A ferramenta dynamodb_data_model_schema_converter converte seu modelo de dados legível por humanos (dynamodb_data_model.md) em um esquema JSON estruturado representando suas tabelas, índices, entidades e padrões de acesso do DynamoDB. Este formato legível por máquina permite a geração de código e pode ser estendido para documentação ou provisionamento de infraestrutura.

A ferramenta valida automaticamente o esquema gerado, fornecendo mensagens de erro detalhadas e sugestões de correção se a validação falhar. A saída é salva em uma pasta com timestamp para isolamento.

Estrutura do Esquema:

O schema.json gerado é uma representação estruturada contendo:

• Tabelas: Uma ou mais definições de tabela do DynamoDB com chaves de partição/ordenação
• Definições de GSI: Configurações de Índice Secundário Global (opcional)
• Entidades: Modelos de domínio (Usuário, Pedido, Produto, etc.) com campos tipados
• Tipos de Campo: string, integer, decimal, boolean, array, object, uuid
• Padrões de Acesso: Operações Query/Scan/GetItem com definições de parâmetros e templates de chave
• Templates de Chave: Padrões para gerar chaves de partição e ordenação (ex., USER#{user_id})

Este formato estruturado serve como entrada para as ferramentas de geração de código.

Validando Arquivos de Esquema

A ferramenta dynamodb_data_model_schema_validator valida seu arquivo schema.json para garantir que esteja formatado corretamente para a geração de código.

Verificações de Validação:

• Seções obrigatórias (table_config, entities) existem
• Todos os campos obrigatórios estão presentes
• Os tipos de campo são válidos (string, integer, decimal, boolean, array, object, uuid)
• Os valores de enum estão corretos (tipos de operação, tipos de retorno)
• Os IDs de padrão são únicos em todas as entidades
• Os nomes dos GSI correspondem entre gsi_list e gsi_mappings
• Os campos referenciados nos templates existem nos campos da entidade
• As condições de intervalo são válidas com contagens de parâmetros corretas
• Os padrões de acesso têm operações e tipos de retorno válidos

Segurança:

Os arquivos de esquema devem estar dentro do diretório de trabalho atual ou subdiretórios. Tentativas de path traversal são bloqueadas por segurança.

Exemplos de Saída da Validação:

Sucesso:

✅ Schema validation passed!

Erro com sugestões:

❌ 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

Gerando Camada de Acesso a Dados

A ferramenta generate_data_access_layer gera código Python com segurança de tipos a partir do seu arquivo schema.json validado.

Código Gerado:

• Classes de Entidade: Modelos Pydantic com validação de campo e segurança de tipos
• Classes de Repositório: Operações CRUD (criar, ler, atualizar, deletar) para cada entidade
• Padrões de Acesso: Operações de consulta e varredura totalmente implementadas a partir do seu esquema
• Repositório Base: Funcionalidade compartilhada para todos os repositórios
• Exemplos de Uso: Código de exemplo demonstrando como usar as classes geradas (opcional)
• Configuração: ruff.toml para qualidade e formatação de código

Pré-requisitos para Geração de Código:

O código Python gerado requer estas dependências de tempo de execução:

• pydantic>=2.0 - Para validação de entidade e segurança de tipos
• boto3>=1.38 - Para operações do DynamoDB

Instale-as no seu projeto:

uv add pydantic boto3
# or
pip install pydantic boto3

Dependências de Desenvolvimento Opcionais:

Para linting e formatação do código gerado:

• ruff==0.15.8 - Linter e formatador Python (recomendado)

Estrutura de Arquivos Gerada:

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

Usando o Código Gerado:

O código gerado fornece classes de entidade com segurança de tipos e métodos de repositório para todos os seus padrões de acesso:

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 e formatação do código gerado com ruff:

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