DynamoDB Read-Only MCP

A server that utilizes the Model Context Protocol (MCP) to query AWS DynamoDB databases. This server allows LLMs like Claude to query DynamoDB data through natural language requests.

Features

This MCP server provides the following features:

Table Management Tools:
- list-tables: View a list of all DynamoDB tables
- describe-table: View detailed information about a specific table
Data Query Tools:
- scan-table: Scan all or part of a table's data
- query-table: Search for data that matches specific conditions in a table
- paginate-query-table: Retrieve data across multiple pages that matches specific conditions
- get-item: Retrieve an item with a specific key
- count-items: Calculate the number of items in a table
Resources:
- dynamodb-tables-info: A resource that provides metadata for all tables
- dynamodb-table-schema: A resource that provides schema information for a specific table
Prompts:
- dynamodb-query-help: A help prompt for writing DynamoDB queries

Installation and Execution

You can run it without installation using the Run with NPX method below.

Installing via Smithery

To install DynamoDB Read-Only Server for Claude Desktop automatically via Smithery:

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

Installation

Clone the repository:

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

Install the required packages:
```
npm install
```

Create a .env file and set up your AWS credentials:

AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=your_region

Build and Run

npm run build
npm start

Connect to Claude Desktop

To use this MCP server with Claude Desktop, you need to modify the Claude Desktop configuration file.

Open the Claude Desktop configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the server configuration as follows:

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

Restart Claude Desktop.

Run with NPX

You can also run this server using npx without a global installation:

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

Usage Examples

You can ask Claude questions like:

"Can you tell me what tables are in DynamoDB?"
"Explain the structure of the Users table"
"Find the number of users in the 'Users' table where groupId is '0lxp4paxk7'"

Architecture

This MCP server consists of the following layered structure:

Client Interface (Claude Desktop) - Interaction between user and LLM
MCP Protocol Layer - Provides standardized message exchange method
DynamoDB Server - Implements functions that interact with DynamoDB
AWS SDK - Communicates with AWS DynamoDB service

Key Operation Mechanisms

1. Initialization and Connection

When the server starts, the following process occurs:

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

StdioServerTransport sets up a communication channel through standard input/output.
server.connect(transport) connects to Claude Desktop through the MCP protocol.
During connection, the server sends information about supported tools, resources, and prompts to the client.

2. Tool Request Processing

When a user asks Claude something like "Show me the list of DynamoDB tables":

Claude analyzes this request and calls the list-tables tool.
This request is sent to the server through the MCP protocol.
The server executes the corresponding tool handler:

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}` }] };
  }
});

The result is returned to Claude through the MCP protocol.
Claude processes this result into natural language and presents it to the user.

3. Specific Parameter Handling

When a user requests "Tell me the structure of the Users table":

Claude determines that this request should use the describe-table tool.
Claude configures the parameter as { tableName: "Users" }.
This information is sent to the MCP server:

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
  }
);

Here, z.string() uses the Zod library to validate parameters.

4. Resource Handling

Resources are another MCP feature that provides read-only data:

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 accesses resources and uses them as context information.

5. Prompt Handling

The MCP server can provide prompt templates for specific tasks:

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 },
        },
      ],
    };
  }
);

This prompt is used when a user requests "Show me how to write queries for the Users table."

Data Flow Summary

User makes a request to Claude in natural language
Claude analyzes the request and selects the appropriate MCP tool/resource/prompt
MCP client sends the request to the server in a standardized format
Server processes the request and calls the AWS DynamoDB API
DynamoDB returns results
Server converts results to MCP format and sends them to the client
Claude processes the results into natural language and presents them to the user

License

This project is licensed under the MIT License - see the LICENSE file for details.