Skip to main content
Glama
dynamodb-mcp-server

dynamodb-mcp-server

by Allentgt

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 — limit and next_token on all read operations

  • Response 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, idempotentHint on every tool

  • DynamoDB 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 http

The 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-server

Install 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-server

Configuration

All configuration is via environment variables:

Variable

Default

Description

AWS_REGION

us-east-1

AWS region for DynamoDB

AWS_ACCESS_KEY_ID

—

AWS access key (or use IAM role)

AWS_SECRET_ACCESS_KEY

—

AWS secret key (or use IAM role)

AWS_ENDPOINT_URL

—

Custom endpoint for DynamoDB Local or LocalStack

MCP_HOST

0.0.0.0

Server bind address

MCP_PORT

8000

Server port

MCP_PATH

/mcp

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-server

MCP 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_tables

List all DynamoDB tables in the configured region. Supports pagination.

read-only, idempotent

describe_table

Get table schema, key definitions, GSIs/LSIs, billing mode, item count, and size.

read-only, idempotent

create_table

Create a new table with partition key, optional sort key, and billing mode.

mutating, not idempotent

create_gsi

Create a Global Secondary Index on a table. Specify key schema and projection type.

mutating, not idempotent

Query & Scan

Tool

Description

Annotations

query_table

Query by key condition expression. Supports GSI/LSI, filter expressions, pagination, and JSON/Markdown output.

read-only, idempotent

scan_table

Full table scan with optional filter expression. Supports pagination and JSON/Markdown output.

read-only, idempotent

Item Operations

Tool

Description

Annotations

add_item

Put a single item. Supports condition expressions to prevent overwrites.

mutating, idempotent

update_item

Update specific attributes with SET, REMOVE, ADD, DELETE expressions. Returns the updated item.

mutating, idempotent

delete_item

Delete a single item by primary key.

destructive, idempotent

bulk_add_items

Batch write up to 500 items using DynamoDB batch_writer with automatic retry.

mutating, idempotent

prune_table

Delete all (or filtered) items from a table. Requires confirm=true as a safety guard.

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.md

Development

Setup

uv sync  # Installs all dependencies including dev group

Running 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 test

Tests 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 formatting

Building

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 deployments

  • Async: All tool handlers are async. DynamoDB calls go through aioboto3 to avoid blocking the event loop

  • Lifespan pattern: app_lifespan() creates a shared aioboto3.Session stored in AppContext, available to all tools via ctx.request_context.lifespan_context

  • Error handling: ClientError exceptions are caught and mapped to actionable messages (e.g., "Table not found — use list_tables to see available tables")

  • Response formatting: Tools support format parameter (json or markdown). Markdown tables are generated for scan/query results

  • Truncation: Responses exceeding 25,000 characters are truncated with a warning and suggestion to use pagination

License

MIT

Available Tools

11 tools
add_itemA
Idempotent

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_itemsA
Idempotent

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_itemA
DestructiveIdempotent

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_tableA
Read-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_tablesA
Read-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_tableA
Destructive

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_tableA
Read-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_tableA
Read-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_itemA
Idempotent

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

    A4.4/5.0

    Scored across 11 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      An 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
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server for managing Amazon DynamoDB resources, providing tools for table management, capacity management, and data operations.
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      An 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.
      -