MCP de solo lectura de DynamoDB

Un servidor que utiliza el Protocolo de Contexto de Modelo (MCP) para consultar bases de datos de AWS DynamoDB. Este servidor permite a los LLM como Claude consultar datos de DynamoDB mediante solicitudes de lenguaje natural.

Características

Este servidor MCP ofrece 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 : escanea todos o parte de los datos de una tabla
- query-table : busca datos que coincidan con condiciones específicas en una tabla
- paginate-query-table : recupera datos de varias páginas que coinciden con condiciones específicas
- get-item : recupera un elemento con una clave específica
- count-items : Calcula 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
Indicaciones :
- dynamodb-query-help : un mensaje de ayuda para escribir consultas de DynamoDB

Instalación y ejecución

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

Instalación

Clonar el repositorio:
git clone https://github.com/jjikky/dynamo-readonly-mcp.git cd dynamo-readonly-mcp
Instalar los paquetes necesarios:
npm install
Cree un archivo .env y configure sus credenciales de AWS:
AWS_ACCESS_KEY_ID=your_access_key AWS_SECRET_ACCESS_KEY=your_secret_key AWS_REGION=your_region

Construir y ejecutar

npm run build
npm start

Conectarse a Claude Desktop

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

Abra el archivo de configuración de Claude Desktop:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Ventanas: %APPDATA%\Claude\claude_desktop_config.json
Agregue 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" } } } }
Reinicie Claude Desktop.

Correr 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 hacerle preguntas a Claude como:

"¿Puedes decirme qué tablas hay en DynamoDB?"
"Explicar la estructura de la tabla Usuarios"
"Encuentre el número de usuarios en la tabla 'Usuarios' donde el ID de grupo es '0lxp4paxk7'"

Arquitectura

Este servidor MCP consta de la siguiente estructura en capas:

Interfaz de cliente (Claude Desktop) : interacción entre el usuario y LLM
Capa de protocolo MCP : proporciona un método de intercambio de mensajes estandarizado
Servidor DynamoDB : implementa funciones que interactúan con DynamoDB
AWS SDK : se comunica con el servicio AWS DynamoDB

Mecanismos de operación clave

1. Inicialización y conexión

Cuando se inicia el servidor, se produce el siguiente proceso:

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error('DynamoDB read-only MCP server is running...');
}

StdioServerTransport configura un canal de comunicación a través de entrada/salida estándar.
server.connect(transport) se conecta a Claude Desktop a través del protocolo MCP.
Durante la conexión, el servidor envía información sobre herramientas, recursos y avisos compatibles al cliente.

2. Procesamiento de solicitudes de herramientas

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

Claude analiza esta solicitud y llama a la herramienta list-tables .
Esta solicitud se envía al servidor a través del protocolo MCP.
El servidor ejecuta el controlador 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}` }] };
  }
});

El resultado se devuelve a Claude a través del protocolo MCP.
Claude procesa este resultado en lenguaje natural y se lo presenta al usuario.

3. Manejo de parámetros específicos

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

Claude determina que esta solicitud debe utilizar la herramienta describe-table .
Claude configura el parámetro como { tableName: "Users" } .
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() usa la biblioteca Zod para validar los 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 rápido

El servidor MCP puede proporcionar plantillas de indicaciones 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 mensaje se utiliza cuando un usuario solicita "Muéstreme cómo escribir consultas para la tabla Usuarios".

Resumen del flujo de datos

El usuario realiza una solicitud a Claude en lenguaje natural
Claude analiza la solicitud y selecciona la herramienta/recurso/mensaje MCP adecuado
El cliente MCP envía la solicitud al servidor en un formato estandarizado
El servidor procesa la solicitud y llama a la API de AWS DynamoDB
DynamoDB devuelve resultados
El servidor convierte los resultados al formato MCP y los envía al cliente
Claude procesa los resultados en lenguaje natural y los presenta al usuario.

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

DynamoDB Read-Only MCP

Integrations