Dynamo Readonly MCP

🚀 DynamoDB Read-Only Console

The DynamoDB Read-Only Console is a server implemented using the DynamoDB Message Protocol (MCP). It allows large language models (LLMs) like Claude to access DynamoDB data through natural language queries. Users can obtain read-only access to DynamoDB tables by sending natural language requests.

✨ Features

Table Management Tools

• List all tables (list-tables): Returns information about all DynamoDB tables.
• Describe a table (describe-table): Retrieves detailed information about a specified table.
• Check table existence (table-exists): Verifies whether a specified table exists.

Data Query Tools

• Basic query (query-table): Queries table data through a key condition expression.
• Advanced query (advanced-query): Supports complex filtering and sorting operations.
• Scan a table (scan-table): Returns all items in the table and can be filtered by conditions.

Resource Management

• Table information resource (dynamodb-tables-info): Provides metadata for all tables.
• Specific table structure (dynamodb-table-schema): Returns the schema information of a specified table.
• Index details (dynamodb-indexes-info): Lists all indexes in the table and their configurations.

Prompt Support

• Query help (dynamodb-query-help): Provides guidance on how to write effective DynamoDB queries.
• Best practice tips (best-practices-tip): Recommends efficient data access strategies.
• Error recovery tips (error-recovery-tip): Provides suggested repair steps when an error occurs.

📦 Installation

Clone the Project

Clone the repository using Git:

git clone https://github.com/yourusername/dynamodb-read-only-console.git

Install Dependencies

After entering the project directory, install the required dependencies:

npm install

Configure Environment Variables

Create and edit the .env file:

DYNAMODB_ENDPOINT=your-endpoint
DYNAMODB_REGION=your-region

Build and Start the Service

Build the project:

npm run build

Start the server:

npm start

Connect to Claude Desktop

Add the following configuration to the clay.json file to enable Claude to connect to your MCP service:

{
  "mcp": {
    "servers": [
      {
        "url": "http://localhost:3000",
        "options": {
          "keepalive": true,
          "family": 4
        }
      }
    ]
  }
}

💻 Usage Examples

Basic Usage

Example 1: Get Information about All Tables

The user sends a query: "Show all DynamoDB tables" Claude calls the list-tables tool and returns the following result:

[
  {
    "TableName": "Users",
    "TableStatus": "ACTIVE",
    "CreationDateTime": "2023-10-01T12:00:00Z"
  },
  {
    "TableName": "Orders",
    "TableStatus": "ACTIVE",
    "CreationDateTime": "2023-10-02T14:30:00Z"
  }
]

Example 2: Describe a Specific Table

The user sends a query: "Tell me the structure of the Users table" Claude calls the describe-table tool, passing the parameter {tableName: "Users"}, and returns the following result:

{
  "TableName": "Users",
  "TableStatus": "ACTIVE",
  "KeySchema": [
    { "AttributeName": "Username", "KeyType": "HASH" },
    { "AttributeName": "UserId", "KeyType": " RANGE" }
  ],
  "ProvisionedThroughput": {
    "ReadCapacityUnits": 10,
    "WriteCapacityUnits": 5
  }
}

Example 3: Scan Table Data

The user sends a query: "List the usernames of all users in the Users table" Claude calls the scan-table tool, passing the filtering condition { TableName: "Users", Filter: { Username: {"contains": "admin"} } }, and returns the following result:

[
  { "Username": "admin123" },
  { "Username": "superuser" },
  { "Username": "administrator" }
]

🔧 Technical Details

Data Flow Summary

1. The user sends a natural language query to Claude.
2. Claude analyzes the request and selects an appropriate MCP tool.
3. Calls the corresponding DynamoDB operation (e.g., query, scan).
4. Processes the returned result and generates a user-friendly response.
5. Returns the result to the user in a structured or natural language format.

📄 License

This project is licensed under the MIT License. Please refer to the LICENSE file for detailed information.