DynamoDB Read-Only MCP

Un servidor de solo lectura para consultar bases de datos AWS DynamoDB utilizando el Model Context Protocol (MCP).

GitHub
2
Prueba este MCPPatrocinado

Documentación

MseeP.ai Security Assessment Badge

DynamoDB Read-Only MCP

npm version smithery badge

Un servidor que utiliza el Protocolo de Contexto de Modelos (MCP) para consultar bases de datos AWS DynamoDB. Este servidor permite que LLMs como Claude consulten datos de DynamoDB mediante solicitudes en lenguaje natural.

DynamoDB Read-Only MCP server

Características

Este servidor MCP proporciona las siguientes características:

  • Herramientas de Gestión de Tablas:
    • list-tables: Ver una lista de todas las tablas de DynamoDB
    • describe-table: Ver información detallada sobre una tabla específica
  • Herramientas de Consulta de Datos:
    • scan-table: Escanear todo o parte de los datos de una tabla
    • query-table: Buscar datos que coincidan con condiciones específicas en una tabla
    • paginate-query-table: Recuperar datos de múltiples páginas que coincidan con condiciones específicas
    • get-item: Recuperar un elemento con una clave específica
    • count-items: Calcular el número de elementos en una tabla
  • Recursos:
    • dynamodb-tables-info: Un recurso que proporciona metadatos para todas las tablas
    • dynamodb-table-schema: Un recurso que proporciona información de esquema para una tabla específica
  • Prompts:
    • dynamodb-query-help: Un prompt de ayuda para escribir consultas de DynamoDB

Instalación y Ejecución

Puedes ejecutarlo sin instalación utilizando el método Run with NPX a continuación.

Instalación mediante Smithery

Para instalar DynamoDB Read-Only Server para Claude Desktop automáticamente mediante Smithery:

npx -y @smithery/cli install @jjikky/dynamo-readonly-mcp --client claude

Instalación

  1. Clona el repositorio:

    git clone https://github.com/jjikky/dynamo-readonly-mcp.git
cd dynamo-readonly-mcp

  2. Instala los paquetes requeridos:

    npm install

  3. Crea un archivo .env y configura tus credenciales de AWS:

    AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=your_region

Compilar y Ejecutar

npm run build
npm start

Conectar a Claude Desktop

Para usar este servidor MCP con Claude Desktop, debes modificar el archivo de configuración de Claude Desktop.

  1. Abre el archivo de configuración de Claude Desktop:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. Agrega la configuración del servidor de la siguiente manera:

    {
  "mcpServers": {
    "dynamodb-readonly": {
      "command": "node",
      "args": ["/absolute-path/dynamo-readonly-mcp/dist/index.js"],
      "env": {
        "AWS_ACCESS_KEY_ID": "your_access_key",
        "AWS_SECRET_ACCESS_KEY": "your_secret_key",
        "AWS_REGION": "your_region"
      }
    }
  }
}

  3. Reinicia Claude Desktop.

Ejecutar con NPX

También puedes ejecutar este servidor usando npx sin una instalación global:

{
  "mcpServers": {
    "dynamodb-readonly": {
      "command": "npx",
      "args": ["-y", "dynamo-readonly-mcp"],
      "env": {
        "AWS_ACCESS_KEY_ID": "your_access_key",
        "AWS_SECRET_ACCESS_KEY": "your_secret_key",
        "AWS_REGION": "your_region"
      }
    }
  }
}

Ejemplos de Uso

Puedes hacer preguntas a Claude como:

  1. "¿Puedes decirme qué tablas hay en DynamoDB?"
  2. "Explica la estructura de la tabla Users"
  3. "Encuentra el número de usuarios en la tabla 'Users' donde groupId es '0lxp4paxk7'"

Arquitectura

Este servidor MCP consta de la siguiente estructura en capas:

  1. Interfaz de Cliente (Claude Desktop) - Interacción entre el usuario y el LLM
  2. Capa de Protocolo MCP - Proporciona un método estandarizado de intercambio de mensajes
  3. Servidor DynamoDB - Implementa funciones que interactúan con DynamoDB
  4. AWS SDK - Se comunica con el servicio AWS DynamoDB

Mecanismos Clave de Operación

1. Inicialización y Conexión

Cuando el servidor se inicia, ocurre el siguiente proceso:

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error('DynamoDB read-only MCP server is running...');
}
  • StdioServerTransport establece un canal de comunicación a través de la entrada/salida estándar.
  • server.connect(transport) se conecta a Claude Desktop mediante el protocolo MCP.
  • Durante la conexión, el servidor envía información sobre las herramientas, recursos y prompts compatibles al cliente.

2. Procesamiento de Solicitudes de Herramientas

Cuando un usuario pregunta a Claude algo como "Muéstrame la lista de tablas de DynamoDB":

  1. Claude analiza esta solicitud y llama a la herramienta list-tables.
  2. Esta solicitud se envía al servidor mediante el protocolo MCP.
  3. El servidor ejecuta el manejador de herramientas correspondiente:
server.tool('list-tables', 'Gets a list of all DynamoDB tables', {}, async () => {
  try {
    const tables = await listTables();
    return {
      content: [{ type: 'text', text: JSON.stringify(tables, null, 2) }],
    };
  } catch (error) {
    return { isError: true, content: [{ type: 'text', text: `Error: ${error.message}` }] };
  }
});
  1. El resultado se devuelve a Claude mediante el protocolo MCP.
  2. Claude procesa este resultado en lenguaje natural y lo presenta al usuario.

3. Manejo de Parámetros Específicos

Cuando un usuario solicita "Dime la estructura de la tabla Users":

  1. Claude determina que esta solicitud debe usar la herramienta describe-table.
  2. Claude configura el parámetro como { tableName: "Users" }.
  3. Esta información se envía al servidor MCP:
server.tool(
  'describe-table',
  'Gets detailed information about a DynamoDB table',
  {
    tableName: z.string().describe('Name of the table to get detailed information for'),
  },
  async ({ tableName }) => {
    // Query table information using the tableName parameter
    const tableInfo = await describeTable(tableName);
    // Return results
  }
);

Aquí, z.string() utiliza la librería Zod para validar parámetros.

4. Manejo de Recursos

Los recursos son otra característica de MCP que proporciona datos de solo lectura:

server.resource('dynamodb-tables-info', 'DynamoDB table information', async () => {
  // Create and return resource data
  const tables = await listTables();
  const tablesInfo = await Promise.all(/* Query table information */);

  return {
    contents: [
      {
        uri: 'dynamodb://tables-info',
        text: JSON.stringify(tablesInfo, null, 2),
        mimeType: 'application/json',
      },
    ],
  };
});

Claude accede a los recursos y los utiliza como información de contexto.

5. Manejo de Prompts

El servidor MCP puede proporcionar plantillas de prompts para tareas específicas:

server.prompt(
  'dynamodb-query-help',
  'A prompt that helps write DynamoDB queries',
  {
    tableName: z.string().describe('Table name to query'),
    queryType: z.enum(['basic', 'advanced']).default('basic'),
  },
  async ({ tableName, queryType }) => {
    // Generate prompt content
    return {
      messages: [
        {
          role: 'user',
          content: { type: 'text', text: helpContent },
        },
      ],
    };
  }
);

Este prompt se utiliza cuando un usuario solicita "Muéstrame cómo escribir consultas para la tabla Users".

Resumen del Flujo de Datos

  1. El usuario hace una solicitud a Claude en lenguaje natural
  2. Claude analiza la solicitud y selecciona la herramienta/recurso/prompt MCP apropiado
  3. El cliente MCP envía la solicitud al servidor en un formato estandarizado
  4. El servidor procesa la solicitud y llama a la API de AWS DynamoDB
  5. DynamoDB devuelve los resultados
  6. El servidor convierte los resultados al formato MCP y los envía al cliente
  7. Claude procesa los resultados en lenguaje natural y los presenta al usuario

Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulte el archivo LICENSE para obtener más detalles.