dynamodb-mcp-server
Provides tools for managing DynamoDB tables and items, including listing, querying, scanning, creating tables and indexes, and CRUD operations on items.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@dynamodb-mcp-server list all my DynamoDB tables"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
dynamodb-mcp-server
An MCP (Model Context Protocol) server that gives LLM agents full access to Amazon DynamoDB. Built with FastMCP and aioboto3, it exposes 11 tools covering table management, querying, scanning, and item CRUD operations. Supports both stdio (for uvx / local clients) and streamable HTTP (for remote deployment).
Features
11 DynamoDB tools — list, describe, create table, query, scan, create GSI, add/update/delete items, bulk add, prune
Dual transport — stdio (default, for
uvx/ Claude Desktop / Cursor) and streamable HTTP (for remote deployment)Async end-to-end — aioboto3 for non-blocking DynamoDB access
Structured input validation — Pydantic models with field descriptions that become tool parameter docs
Dual output formats — JSON or Markdown, controlled per request
Pagination —
limitandnext_tokenon all read operationsResponse truncation — enforces a 25,000 character limit to stay within LLM context windows
Actionable errors — every error message tells the agent what to do next
Tool annotations —
readOnlyHint,destructiveHint,idempotentHinton every toolDynamoDB Local / LocalStack support — connect to local instances via
AWS_ENDPOINT_URL
Related MCP server: MCP SQL Server
Quick Start
Prerequisites
Python 3.14+
uv package manager
AWS credentials configured (via environment variables,
~/.aws/credentials, or IAM role)
Install and Run
# Clone the repository
git clone https://github.com/Allentgt/dynamodb-mcp-server.git
cd dynamodb-mcp-server
# Install dependencies
uv sync
# Run the server (stdio transport, default)
uv run dynamodb-mcp-server
# Run with HTTP transport for remote deployment
uv run dynamodb-mcp-server --transport httpThe default transport is stdio (for local MCP clients). Use --transport http to start a streamable HTTP server on http://0.0.0.0:8008/mcp.
Install via uvx (no clone needed)
uvx --from git+https://github.com/Allentgt/dynamodb-mcp-server.git dynamodb-mcp-serverInstall from Wheel
# Build the package
uv build
# Install the wheel
uv pip install dist/dynamodb_mcp_server-0.1.0-py3-none-any.whl
# Run via console script
dynamodb-mcp-serverConfiguration
All configuration is via environment variables:
Variable | Default | Description |
|
| AWS region for DynamoDB |
| — | AWS access key (or use IAM role) |
| — | AWS secret key (or use IAM role) |
| — | Custom endpoint for DynamoDB Local or LocalStack |
|
| Server bind address |
|
| Server port |
|
| Streamable HTTP endpoint path |
Using with DynamoDB Local
# Start DynamoDB Local (Docker)
docker run -p 8000:8000 amazon/dynamodb-local
# Point the MCP server at it (use a different port to avoid conflict)
$env:AWS_ENDPOINT_URL = "http://localhost:8000" # PowerShell
export AWS_ENDPOINT_URL="http://localhost:8000" # Bash
$env:MCP_PORT = "8001" # PowerShell
export MCP_PORT=8001 # Bash
uv run dynamodb-mcp-serverMCP Client Configuration
Recommended: stdio via uvx (Claude Desktop, Cursor, etc.)
{
"mcpServers": {
"dynamodb": {
"command": "uvx",
"args": [
"--from", "git+https://github.com/Allentgt/dynamodb-mcp-server.git",
"dynamodb-mcp-server"
],
"env": {
"AWS_REGION": "us-east-1",
"AWS_ACCESS_KEY_ID": "your-key",
"AWS_SECRET_ACCESS_KEY": "your-secret",
"AWS_ENDPOINT_URL": "http://localhost:8000"
}
}
}
}Alternative: remote HTTP server
{
"mcpServers": {
"dynamodb": {
"url": "http://localhost:8008/mcp"
}
}
}Tools
Table Management
Tool | Description | Annotations |
| List all DynamoDB tables in the configured region. Supports pagination. | read-only, idempotent |
| Get table schema, key definitions, GSIs/LSIs, billing mode, item count, and size. | read-only, idempotent |
| Create a new table with partition key, optional sort key, and billing mode. | mutating, not idempotent |
| Create a Global Secondary Index on a table. Specify key schema and projection type. | mutating, not idempotent |
Query & Scan
Tool | Description | Annotations |
| Query by key condition expression. Supports GSI/LSI, filter expressions, pagination, and JSON/Markdown output. | read-only, idempotent |
| Full table scan with optional filter expression. Supports pagination and JSON/Markdown output. | read-only, idempotent |
Item Operations
Tool | Description | Annotations |
| Put a single item. Supports condition expressions to prevent overwrites. | mutating, idempotent |
| Update specific attributes with SET, REMOVE, ADD, DELETE expressions. Returns the updated item. | mutating, idempotent |
| Delete a single item by primary key. | destructive, idempotent |
| Batch write up to 500 items using DynamoDB batch_writer with automatic retry. | mutating, idempotent |
| Delete all (or filtered) items from a table. Requires | destructive, not idempotent |
Tool Usage Examples
List tables
{ "limit": 10 }Create a table
{
"table_name": "orders",
"partition_key": "PK",
"sort_key": "SK",
"sort_key_type": "S",
"billing_mode": "PAY_PER_REQUEST"
}Query with key condition
{
"table_name": "orders",
"key_condition_expression": "PK = :pk AND begins_with(SK, :prefix)",
"expression_attribute_values": { ":pk": "USER#123", ":prefix": "ORDER#" },
"format": "markdown"
}Add an item with overwrite protection
{
"table_name": "users",
"item": { "PK": "USER#456", "name": "Alice", "email": "alice@example.com" },
"condition_expression": "attribute_not_exists(PK)"
}Update specific attributes
{
"table_name": "users",
"key": { "PK": "USER#456" },
"update_expression": "SET #n = :name, email = :email",
"expression_attribute_names": { "#n": "name" },
"expression_attribute_values": { ":name": "Bob", ":email": "bob@example.com" }
}Bulk add items
{
"table_name": "products",
"items": [
{ "PK": "PROD#1", "name": "Widget", "price": 9.99 },
{ "PK": "PROD#2", "name": "Gadget", "price": 19.99 }
]
}Prune table (with safety confirmation)
{
"table_name": "logs",
"confirm": true,
"filter_expression": "created_at < :cutoff",
"expression_attribute_values": { ":cutoff": "2024-01-01" }
}Project Structure
dynamodb-mcp-server/
src/dynamodb_mcp_server/
__init__.py
__main__.py # Entry point — registers tools, starts server
server.py # FastMCP instance, AppContext, lifespan
models.py # Pydantic input models for all 10 tools
utils.py # JSON encoding, error handling, truncation, formatting
tools/
__init__.py
table_management.py # list_tables, describe_table, create_gsi
query_scan.py # query_table, scan_table
item_operations.py # add_item, delete_item, update_item, bulk_add_items, prune_table
tests/
conftest.py # Async mock wrappers over moto, fixtures
test_table_management.py
test_query_scan.py
test_item_operations.py
test_utils.py
main.py # Backward-compat shim
pyproject.toml
AGENTS.mdDevelopment
Setup
uv sync # Installs all dependencies including dev groupRunning Tests
uv run pytest # Run all 72 tests
uv run pytest -x # Stop on first failure
uv run pytest -v # Verbose output
uv run pytest tests/test_query_scan.py::test_query_table # Single testTests use moto to mock DynamoDB locally. No AWS credentials or network access required.
Linting & Formatting
uv run ruff check . # Lint
uv run ruff check --fix . # Lint with auto-fix
uv run ruff format . # Format
uv run ruff format --check . # Check formattingBuilding
uv build # Produces .tar.gz and .whl in dist/Architecture Notes
Transport: Stdio (default) for local clients like
uvx, Claude Desktop, Cursor. Streamable HTTP (--transport http) for remote/shared deploymentsAsync: All tool handlers are async. DynamoDB calls go through aioboto3 to avoid blocking the event loop
Lifespan pattern:
app_lifespan()creates a sharedaioboto3.Sessionstored inAppContext, available to all tools viactx.request_context.lifespan_contextError handling:
ClientErrorexceptions are caught and mapped to actionable messages (e.g., "Table not found — use list_tables to see available tables")Response formatting: Tools support
formatparameter (jsonormarkdown). Markdown tables are generated for scan/query resultsTruncation: Responses exceeding 25,000 characters are truncated with a warning and suggestion to use pagination
License
MIT
Available Tools
11 toolsadd_itemAIdempotent
Add (put) a single item to a DynamoDB table.
Creates a new item or replaces an existing item with the same primary key. Use condition_expression='attribute_not_exists(PK)' to prevent overwrites.
When to use:
To create a new item in a table
To replace an entire existing item
When NOT to use:
To update specific attributes (use update_item instead)
To add many items at once (use bulk_add_items instead)
Returns: JSON confirmation with the item's primary key.
Inputs: input (required). Returns: result
bulk_add_itemsAIdempotent
Add multiple items to a DynamoDB table in efficient batches.
Uses batch_writer which automatically handles batching (25 items per batch), retries on unprocessed items, and flushing. Items with the same primary key will overwrite existing items.
When to use:
To add many items at once (more efficient than repeated add_item calls)
For data loading or migration scenarios
When NOT to use:
For a single item (use add_item instead)
When you need conditional writes (batch_writer doesn't support conditions)
Returns: JSON confirmation with the count of items added.
Inputs: input (required). Returns: result
create_gsiA
Create a Global Secondary Index (GSI) on a DynamoDB table.
GSIs enable querying on non-primary-key attributes. The table must be in ACTIVE status. Index creation is asynchronous — use describe_table to monitor progress.
When to use:
To enable queries on attributes that aren't part of the primary key
To create alternative access patterns for existing data
When NOT to use:
If a suitable GSI already exists (check with describe_table first)
If the table is not in ACTIVE status
Returns: JSON confirming the GSI creation was initiated with index details.
Inputs: input (required). Returns: result
create_tableA
Create a new DynamoDB table.
Creates a table with a partition key and optional sort key. Defaults to on-demand billing (PAY_PER_REQUEST). Use describe_table to monitor the table until it reaches ACTIVE status.
When to use:
To create a new table for storing data
When setting up a new access pattern
When NOT to use:
If the table already exists (check with list_tables or describe_table first)
Returns: JSON with table name, status, key schema, and billing mode.
Inputs: input (required). Returns: result
delete_itemADestructiveIdempotent
Delete a single item from a DynamoDB table by its primary key.
The item is permanently removed. Use condition_expression to ensure the item exists before deleting.
When to use:
To remove a specific item from a table
When you know the item's full primary key
When NOT to use:
To delete all items (use prune_table instead)
To delete by non-key attributes (scan first, then delete)
Returns: JSON confirmation with the deleted item's key.
Inputs: input (required). Returns: result
describe_tableARead-onlyIdempotent
Get detailed information about a DynamoDB table's schema and configuration.
Returns key schema, attribute definitions, GSIs/LSIs, billing mode, item count, table size, and table status.
When to use:
To understand a table's key schema before querying
To check what GSIs exist before creating a new one
To verify table status (ACTIVE, CREATING, UPDATING, etc.)
To check item count and table size
When NOT to use:
To list tables (use list_tables instead)
Returns: JSON with table name, status, key schema, attribute definitions, indexes, billing mode, item count, and size in bytes.
Inputs: input (required). Returns: result
list_tablesARead-onlyIdempotent
List all DynamoDB tables in the configured AWS region.
Returns table names with pagination support. Use this as a starting point to discover available tables before querying or scanning.
When to use:
To discover which tables exist in the account
To find a table name before using describe_table, query_table, or scan_table
Returns: JSON with 'table_names' list, 'count', and optional 'next_table_name' for pagination.
Inputs: input (required). Returns: result
prune_tableADestructive
Delete all items (or filtered items) from a DynamoDB table.
Scans the table and batch-deletes all matching items. The table itself is preserved — only items are removed. Requires confirm=true.
WARNING: This is a destructive operation. Without a filter_expression, ALL items in the table will be permanently deleted.
When to use:
To clear all data from a table while keeping the table structure
To delete items matching specific criteria (with filter_expression)
For test data cleanup
When NOT to use:
To delete the table itself (not supported by this server)
To delete a single item (use delete_item instead)
Returns: JSON with the count of items deleted.
Inputs: input (required). Returns: result
query_tableARead-onlyIdempotent
Query a DynamoDB table using key conditions to find matching items.
Queries are efficient because they use the table's primary key or GSI/LSI keys. Results are returned sorted by sort key. Optional filter expressions can further refine results (but don't reduce read capacity consumed).
When to use:
To find items by primary key (partition key + optional sort key condition)
To find items using a GSI or LSI
When you know the partition key value
When NOT to use:
When you don't know the partition key (use scan_table instead)
For full-table searches (use scan_table with filter)
Returns: Items matching the query with count, scanned_count, and pagination key. Format controlled by 'format' parameter (json or markdown).
Inputs: input (required). Returns: result
scan_tableARead-onlyIdempotent
Scan a DynamoDB table to read all items, optionally filtering results.
Scans read every item in the table (or index), consuming read capacity proportional to table size regardless of filters. Use queries when possible.
When to use:
To browse all items in a table
When you don't know the partition key value
For ad-hoc searches across all items
When NOT to use:
When you know the partition key (use query_table — much more efficient)
For large tables without filters (expensive and slow)
Returns: Items from the scan with count, scanned_count, and pagination key. Format controlled by 'format' parameter (json or markdown).
Inputs: input (required). Returns: result
update_itemAIdempotent
Update specific attributes of an item in a DynamoDB table.
Modifies only the specified attributes without replacing the entire item. Supports SET, REMOVE, ADD, and DELETE operations in the update expression. Returns the updated item's attributes.
When to use:
To modify specific attributes of an existing item
To increment counters (SET count = count + :inc)
To add/remove elements from sets
To remove attributes from an item
When NOT to use:
To replace an entire item (use add_item instead)
To update many items at once (iterate with update_item or use bulk operations)
Returns: JSON with the updated item attributes.
Inputs: input (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool targets a distinct operation: table listing, description, creation, index creation, item add/update/delete, bulk add, prune, query, and scan. The descriptions include clear 'When to use' and 'When NOT to use' sections that explicitly differentiate overlapping operations like add_item vs bulk_add_items and delete_item vs prune_table.
All tools follow a consistent verb_noun snake_case pattern (list_tables, describe_table, create_table, add_item, delete_item, update_item, query_table, scan_table, etc.). Compound verbs like bulk_add_items and prune_table still adhere to the same convention, so the naming is predictable and uniform.
11 tools is well-scoped for a DynamoDB server, covering table management, item CRUD, batch operations, indexing, and query/scan patterns. Each tool serves a clear purpose without unnecessary bloat, fitting comfortably within the 3-15 tool range.
The set covers item lifecycle well (create, read via query/scan, update, delete) and includes table creation, listing, and description. However, there is no delete_table tool, and prune_table explicitly notes that deleting the table itself is not supported. Also missing are table update operations (e.g., changing billing mode) and GSI deletion, leaving notable lifecycle gaps.
Maintenance
Related MCP Connectors
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Hosted Amazon Seller Central and Amazon Ads MCP server for Claude, ChatGPT, Cursor, and agents.
The Remote MCP server acts as a standardized bridge between LLM applications (like Claude, ChatGPT, and Cursor) and external services, enabling AI agents to access external tools and resources. Its primary capability is providing a centralized search tool to discover other MCP servers and their respective tools. Unlike local implementations, it runs remotely with OAuth authentication and permission controls for security.
Related MCP Servers
- AlicenseBqualityDmaintenanceA server that enables LLMs like Claude to query AWS DynamoDB databases through natural language requests, supporting table management, data querying, and schema analysis.722 npm2MIT
- FlicenseAqualityDmaintenanceAn MCP server that connects LLMs to SQL databases for development assistance, enabling query execution, schema exploration, and data manipulation while providing safety controls against destructive operations.5-
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server for managing Amazon DynamoDB resources, providing tools for table management, capacity management, and data operations.1MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that exposes PostgreSQL/MySQL/SQLite/MongoDB databases to AI agents, converting natural language questions into SQL queries with configurable LLM providers and safe read-only operations.-