DynamoDB MCP Server

Note: This package is part of the MCP Servers monorepo. For the latest updates and full source code, visit the DynamoDB MCP Server directory.

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