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`)

Tool	Description
`list_tables`	List all DynamoDB tables with pagination
`describe_table`	Get table metadata, schema, and indexes
`get_item`	Retrieve single item by primary key
`query_items`	Query items using key conditions
`scan_table`	Scan table with optional filters
`batch_get_items`	Get multiple items across tables

ReadWrite Tools (Group: `readwrite`)

Tool	Description
`put_item`	Create or replace an item
`update_item`	Update specific attributes
`delete_item`	Delete item by primary key
`batch_write_items`	Batch put/delete operations

Admin Tools (Group: `admin`)

Tool	Description
`create_table`	Create a new table
`delete_table`	Delete a table and all data
`update_table`	Update table settings

Configuration

Environment Variables

Variable	Required	Description
`AWS_REGION`	Yes	AWS region (or `AWS_DEFAULT_REGION`)
`AWS_ACCESS_KEY_ID`	No	AWS access key (uses credential chain if not set)
`AWS_SECRET_ACCESS_KEY`	No	AWS secret key (uses credential chain if not set)
`DYNAMODB_ENDPOINT`	No	Custom endpoint (for local DynamoDB)
`DYNAMODB_ENABLED_TOOL_GROUPS`	No	Comma-separated groups: `readonly`, `readwrite`, `admin`
`DYNAMODB_ENABLED_TOOLS`	No	Whitelist specific tools
`DYNAMODB_DISABLED_TOOLS`	No	Blacklist specific tools
`DYNAMODB_ALLOWED_TABLES`	No	Restrict operations to specific tables (comma-separated)

Tool Access Control

Control which tools are available using three methods:

1. Tool Groups (recommended for most cases):

# Read-only access
DYNAMODB_ENABLED_TOOL_GROUPS="readonly"

# Read and write, no table management
DYNAMODB_ENABLED_TOOL_GROUPS="readonly,readwrite"

# All operations (default)
DYNAMODB_ENABLED_TOOL_GROUPS="readonly,readwrite,admin"

2. Whitelist Specific Tools:

# Only allow specific operations
DYNAMODB_ENABLED_TOOLS="get_item,query_items,scan_table"

3. Blacklist Specific Tools:

# Enable all except dangerous operations
DYNAMODB_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 tables
DYNAMODB_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/dynamodb
npm run install-all
npm run build

Testing

# Unit tests
npm run test:run

# Integration tests
npm run test:integration

# Manual tests (requires AWS credentials)
npm run test:manual

Resources

Resource	Description
`dynamodb://config`	Server configuration and tool group mappings

License

MIT

dynamodb