DynamoDB Read-Only

You can run a read-only MCP server for DynamoDB that lets you query DynamoDB data using natural language through Claude Desktop. It exposes tools to list tables, describe tables, scan and query data, fetch items, count items, and provides metadata and prompts to help you form DynamoDB queries. This setup keeps your DynamoDB data accessible to LLMs in a safe, read-only way.

How to use

Install and run the DynamoDB Read-Only MCP Server, then connect it to Claude Desktop. The server exposes tools like list-tables, describe-table, scan-table, query-table, paginate-query-table, get-item, and count-items, plus resources and a query-help prompt. In Claude Desktop, you can ask questions such as “What tables exist in DynamoDB?”, “What is the schema of the Users table?”, or “How many items are in the Users table where groupId equals '0lxp4paxk7'?” to retrieve data through natural language.

To use the NPX method, run Claude Desktop with the MCP server via NPX so you don’t install the server globally. The server remains ready to answer DynamoDB queries while you work.

How to install

Prerequisites you need before starting: Node.js and npm, and access to your AWS credentials with permission to read DynamoDB tables.

Option A: Install via Smithery (automatic for Claude Desktop)

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

Option B: Manual installation from source (local run)

Clone the repository and install dependencies, then set up AWS credentials.

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

npm install

Create your AWS credentials file with the required values (do not share these).

AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=your_region

Build and start the server in the normal development flow.

npm run build
npm start

Additional configuration and usage notes

Two MCP connection options are supported in practice. You can connect via a local stdio server (direct node process) or run through NPX for convenience.

Configs shown below are examples you can adapt for your environment. Ensure you replace placeholders with your actual AWS credentials and paths.

Connection options and examples

If you connect Claude Desktop to a local Node process, you can start the MCP server with a direct Node command and point Claude to the built index file. The following example shows the CLI configuration you would place in Claude Desktop’s MCP settings.

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

Run with NPX

You can run the MCP server without a local install by using NPX. This keeps your environment clean and allows quick testing.

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

Security and best practices

Treat DynamoDB data as read-only. Use IAM policies that permit only the necessary read actions. Never expose secret keys in plain text files or logs. Rotate credentials regularly and consider using role-based access where possible.

Troubleshooting

If Claude cannot access the DynamoDB data, verify that your AWS credentials are correct and that the configured region matches the tables you are querying. Check network access from your host to AWS service endpoints and ensure the MCP server is running and reachable by Claude Desktop.

Available tools

list-tables

List all DynamoDB tables available in your account and region.

describe-table

Retrieve detailed information about a specific DynamoDB table, including key schema and provisioned throughput.

scan-table

Scan through table data, optionally with filters or limits.

query-table

Query data in a table using key conditions and filters.

paginate-query-table

Query data across multiple pages to retrieve large result sets.

get-item

Fetch a single item by its primary key.

count-items

Count the number of items in a table.

dynamodb-tables-info

Resource providing metadata for all DynamoDB tables.

dynamodb-table-schema

Resource providing schema information for a specific table.

dynamodb-query-help

Prompt template to assist in writing DynamoDB queries.