Dynamodb

DynamoDB MCP Server

An MCP server for AWS DynamoDB with fine-grained tool control. Provides comprehensive DynamoDB operations with configurable access levels.

Features

• Complete DynamoDB Operations: Tables, items, queries, scans, and batch operations
• Fine-grained Access Control: Enable/disable tools by group or individually
• Table-level Access Control: Restrict operations to specific tables
• AWS Credential Support: Works with explicit credentials or AWS credential chain
• Custom Endpoints: Support for local DynamoDB or LocalStack

Available Tools

Tool names are kept short since MCP clients typically prefix them with the server name (e.g., dynamodb:list_tables).

Readonly Tools (Group: readonly)

ReadWrite Tools (Group: readwrite)

Admin Tools (Group: admin)

Configuration

Environment Variables

Tool Access Control

Control which tools are available using three methods:

1. Tool Groups (recommended for most cases):

# Read-only accessDYNAMODB_ENABLED_TOOL_GROUPS="readonly"
# Read and write, no table managementDYNAMODB_ENABLED_TOOL_GROUPS="readonly,readwrite"
# All operations (default)DYNAMODB_ENABLED_TOOL_GROUPS="readonly,readwrite,admin"

2. Whitelist Specific Tools:

# Only allow specific operationsDYNAMODB_ENABLED_TOOLS="get_item,query_items,scan_table"

3. Blacklist Specific Tools:

# Enable all except dangerous operationsDYNAMODB_DISABLED_TOOLS="delete_table,create_table"

Priority: DYNAMODB_ENABLED_TOOLS > DYNAMODB_DISABLED_TOOLS > DYNAMODB_ENABLED_TOOL_GROUPS

Table-level Access Control

Restrict all operations to specific tables only:

# Only allow access to Users and Orders tablesDYNAMODB_ALLOWED_TABLES="Users,Orders"

When DYNAMODB_ALLOWED_TABLES is set:

• list_tables only returns tables in the allowed list
• Operations on non-allowed tables return an "Access denied" error
• Batch operations fail if any table in the request is not allowed
• Table names are matched case-sensitively (DynamoDB table names are case-sensitive)
• When using pagination with list_tables, the limit applies before filtering

Note: If not set or set to an empty string, all tables are accessible (no filtering).

This is useful for:

• Multi-tenant environments where each client should only access their tables
• Development environments where you want to protect production tables
• Limiting the blast radius of AI agents to specific tables

Claude Desktop Configuration

Add to your claude_desktop_config.json:

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

{  "mcpServers": {    "dynamodb": {      "command": "npx",      "args": ["-y", "aws-dynamodb-mcp-server"],      "env": {        "AWS_REGION": "us-east-1",        "AWS_ACCESS_KEY_ID": "your-access-key",        "AWS_SECRET_ACCESS_KEY": "your-secret-key",        "DYNAMODB_ENABLED_TOOL_GROUPS": "readonly,readwrite"      }    }  }}

Using Local DynamoDB

For development with local DynamoDB or LocalStack:

{  "mcpServers": {    "dynamodb-local": {      "command": "npx",      "args": ["-y", "aws-dynamodb-mcp-server"],      "env": {        "AWS_REGION": "us-east-1",        "AWS_ACCESS_KEY_ID": "local",        "AWS_SECRET_ACCESS_KEY": "local",        "DYNAMODB_ENDPOINT": "http://localhost:8000"      }    }  }}

Examples

Query Items

Query all orders for customer "C123" from the last 30 days:- Table: Orders- Key condition: customerId = :cid AND orderDate > :date- Values: {":cid": "C123", ":date": "2025-01-01"}

Create Table

Create a Users table with:- Partition key: userId (String)- Billing: Pay per request

Batch Operations

Get user profiles for IDs: user1, user2, user3 from the Users table

Development

Setup

cd experimental/dynamodbnpm run install-allnpm run build

Testing

# Unit testsnpm run test:run
# Integration testsnpm run test:integration
# Manual tests (requires AWS credentials)npm run test:manual

Resources

License

MIT