CategoryWeightCategory scoreContribution

Securityprompt, exec, net, exfil, eval

35%

26.3 pts

Supply chainhash, typosquat, maintainer, lockfile

20%

100

20.0 pts

Maintenancestaleness, pinning, CI

15%

100

15.0 pts

TransparencySKILL.md, perms, README

15%

100

15.0 pts

Communityinstalls, verify, response

15%

100

15.0 pts

Findings & checks · 1 flagged

Securityscore 75 · 1 finding

HIGH"Ignore previous instructions" command embedded in the skillSS-SKILL-INJECT-IGNORE-01 · Prompt injection · README.md

HIGH — when it fires on hostile content the impact is full system-prompt override.

Why it matters

The text {match} is the classic direct prompt-injection phrasing. Placed in a skill body that the agent reads as trusted instructions, it tries to make the agent abandon its prior rules and follow whatever comes next — a full system-prompt override.

The exact value spotted

excerptREADME.md· markdown

458environment or IAM role. The LLM sees tool *results*, never config.

459- **Prompt injection risk.** DynamoDB items are user-generated data. A malicious

460item could contain text designed to influence LLM behavior (e.g. "ignore

461previous instructions and..."). This is inherent to any system that feeds

462untrusted data into an LLM. Mitigations: restrict table access via

463`DDB_ALLOWED_TABLES` to trusted tables, enable human-in-the-loop approval for

Occurrences

1 occurrence · at L460

How to fix

Remove the override phrase, or rephrase the passage so it does not instruct the agent to discard its rules.

Delete the ignore/disregard/forget … previous instructions sentence.
If this is jailbreak-research or tutorial content, move the example into a clearly fenced, non-instruction block and label it as a quoted sample.

Framework references

OWASPLLM01 ATLASAML.T0051

Trace & refs

ruleSS-SKILL-INJECT-IGNORE-01sha25612257180cc9c3254…rubric 365aacaView on GitHub

Supply chainscore 100 · 0 findings

✓—All supply chain checks passedNo findings in this category for the latest scan.pass

Maintenancescore 100 · 0 findings

✓—All maintenance checks passedNo findings in this category for the latest scan.pass

Transparencyscore 100 · 0 findings

✓—All transparency checks passedNo findings in this category for the latest scan.pass

Communityscore 100 · 0 findings

✓—All community checks passedNo findings in this category for the latest scan.pass

The primary manifest — the file an agent reads to learn what this artifact does.

README.md · 1 file

README.md21.8 KB · Markdown

ddb-explorer-mcp

Read-only <a href="https://modelcontextprotocol.io">MCP</a> server for Amazon DynamoDB Safe exploration, querying, and schema discovery from your AI coding assistant.

One-click install

Add ddb-explorer-mcp to your IDE in one click:

Or install from the command line:

# Smithery (auto-configures your client)
npx -y @smithery/cli install ddb-explorer-mcp --client cursor

# Claude Code CLI
claude mcp add ddb-explorer -- uvx ddb-explorer-mcp

# npm wrapper (delegates to uvx under the hood)
npx ddb-explorer-mcp

Why ddb-explorer-mcp?

Write operations are structurally not exposed. The LLM cannot call PutItem, UpdateItem, DeleteItem, BatchWriteItem, TransactWriteItems, CreateTable, DeleteTable, or UpdateTable because those tools are not registered with the server. Not a config flag — they physically do not exist in the tool namespace.


Safe by construction	Read-only tool surface; no writes possible
Eight practical tools	list / describe / get / batch-get / query / scan + schema discovery helpers
Two transports	stdio (local) or streamable-HTTP (hosted)
Works everywhere	Cursor, Claude Desktop, VS Code, Windsurf, Zed, Claude Code CLI, any MCP client
Standard AWS creds	Env vars, profiles, SSO, IMDS all just work
Guardrails for scans	Default `max_pages=1`, hard caps on limits (all configurable via env vars), auto-pagination for `query`
Smart batch ops	`batch_get_item` auto-chunks into 100s and retries `UnprocessedKeys`
JSON-clean output	`Decimal`, `set`, `bytes` coerced to JSON-native types

Installation

For end users (individual, stdio mode)

uvx ddb-explorer-mcp

That's it. uv downloads, caches, and runs the server in an isolated environment on first use.

From a local clone

Clone the repo and the MCP server auto-registers in Cursor and VS Code:

git clone https://github.com/mudassirgithub/ddb-explorer-mcp.git
cd ddb-explorer-mcp
make setup          # installs Python + all dependencies via uv

Open the cloned folder in your IDE:

Cursor — reads .cursor/mcp.json automatically. Restart Cursor, then

check Settings → Tools & MCP. The server appears as ddb-explorer.

VS Code — reads .vscode/mcp.json automatically (native MCP support in

VS Code 1.99+). No extension required.

Claude Code CLI — register the local server manually:

  claude mcp add ddb-explorer -- uv run --directory /path/to/ddb-explorer-mcp ddb-explorer-mcp

Claude Desktop / Windsurf / other clients — copy the config from

examples/cursor-local.json and replace the path with your clone directory.

Edit AWS_REGION / AWS_PROFILE in the relevant MCP config to match your environment. Changes to the Python source are picked up on the next server restart — no reinstall needed.

#### Makefile targets

Target	What it does
`make setup`	Install Python + dependencies via `uv sync`
`make run`	Start the server in stdio mode
`make run-http`	Start the server in HTTP mode on `localhost:8765`
`make test`	Run the test suite (uses moto — no real AWS creds needed)
`make lint`	Lint with ruff
`make format`	Auto-format with ruff
`make check`	Run lint + format-check + tests (same as CI)
`make clean`	Remove build/cache artifacts

For teams (hosted HTTP mode)

docker run --rm -p 8765:8765 \
  -e MCP_TRANSPORT=http \
  -e MCP_HOST=0.0.0.0 \
  -e AWS_REGION=us-east-2 \
  -e AWS_ACCESS_KEY_ID=... \
  -e AWS_SECRET_ACCESS_KEY=... \
  ghcr.io/mudassirgithub/ddb-explorer-mcp:latest

See HTTP deployment below.

Client configuration

Ready-to-paste configs are also available in the examples/ directory.

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "ddb-explorer": {
      "command": "uvx",
      "args": ["ddb-explorer-mcp"],
      "env": {
        "AWS_PROFILE": "default",
        "AWS_REGION": "us-east-2"
      }
    }
  }
}

Restart Cursor (⌘Q on macOS). Open Settings → Tools & MCP to verify.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "ddb-explorer": {
      "command": "uvx",
      "args": ["ddb-explorer-mcp"],
      "env": {
        "AWS_PROFILE": "default",
        "AWS_REGION": "us-east-2"
      }
    }
  }
}

Claude Code CLI

claude mcp add ddb-explorer \
  --env AWS_PROFILE=default \
  --env AWS_REGION=us-east-2 \
  -- uvx ddb-explorer-mcp

VS Code (with Cline, Continue, or native MCP)

Add to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "ddb-explorer": {
        "command": "uvx",
        "args": ["ddb-explorer-mcp"],
        "env": {
          "AWS_PROFILE": "default",
          "AWS_REGION": "us-east-2"
        }
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "ddb-explorer": {
      "command": "uvx",
      "args": ["ddb-explorer-mcp"],
      "env": {
        "AWS_PROFILE": "default",
        "AWS_REGION": "us-east-2"
      }
    }
  }
}

Remote HTTP (any client)

{
  "mcpServers": {
    "ddb-explorer": {
      "type": "streamableHttp",
      "url": "https://ddb-explorer.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Tools reference

Tool	Purpose
`list_tables(name_contains?)`	List tables in the region, optionally filtered by substring
`describe_table(table_name)`	Full description: keys, attrs, GSIs, LSIs, TTL, item count, size
`get_indexes(table_name)`	Trimmed view — just the secondary indexes
`sample_items(table_name, n?)`	Fetch a few items to discover the schemaless attribute shape
`get_item(table_name, key, consistent_read?)`	Single-item read by primary key
`batch_get_item(table_name, keys[], consistent_read?)`	Many items by PK, auto-chunked into 100s, retries `UnprocessedKeys`
`query(table_name, key_condition_expression, expression_attribute_values, ...)`	Query base table or GSI/LSI with full DynamoDB expression syntax
`scan(table_name, filter_expression?, max_pages?, ...)`	Scan with safe pagination caps (default `max_pages=1`, hard cap 20)

Example prompts

"List all tables with order in the name and describe the newest one."

"Query prod-orders where user_id = 'U123' and created_at > '2026-01-01', using the by_user_created GSI, limit 20."

"Sample 5 items from prod-events and tell me which attributes are always present."

"Compare the schemas of prod-orders and staging-orders — are there attributes in one that don't exist in the other?"

See examples/PROMPTS.md for more.

Configuration

All configuration is via environment variables.

AWS credentials / region

The server uses the standard boto3 credential resolution chain. The first valid source wins:

AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY (+ optional AWS_SESSION_TOKEN) env vars
AWS_PROFILE pointing to a profile in ~/.aws/credentials or ~/.aws/config
AWS SSO cache
IAM role attached to the execution context (EC2 instance profile, ECS task role, Lambda role)

Variable	Default	Purpose
`AWS_REGION`	`us-east-2`	DynamoDB region
`AWS_DEFAULT_REGION`	—	Fallback for region
`AWS_PROFILE`	—	Named profile to use
`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN`	—	Explicit credentials

Transport

Variable	Default	Purpose
`MCP_TRANSPORT`	`stdio`	`stdio` \	`http` \	`sse`
`MCP_HOST`	`127.0.0.1`	HTTP bind host (use `0.0.0.0` to expose)
`MCP_PORT`	`8765`	HTTP bind port

Safety limits

All tool safety caps are configurable via environment variables. Defaults match the original hardcoded values — existing deployments are unaffected unless you explicitly override them.

Variable	Default	Purpose	Cost / data implications
`DDB_SCAN_MAX_LIMIT`	`500`	Hard cap on items per scan page	Most impactful. Scans read every item in the table. On large prod tables (millions of items), high limits burn RCUs and can return sensitive data into the LLM context. Consider `50`–`100` for production.
`DDB_SCAN_DEFAULT_LIMIT`	`50`	Default items per scan page (when caller omits `limit`)	Safety net — keeps casual/unparameterized scans small.
`DDB_SCAN_MAX_PAGES`	`20`	Hard cap on pages per scan call	Combined with `SCAN_MAX_LIMIT`, this controls the maximum blast radius of a single scan. `20 pages × 500 items = 10,000 items` worst case. Lower to `3`–`5` on production.
`DDB_SCAN_DEFAULT_MAX_PAGES`	`1`	Default pages per scan (when caller omits `max_pages`)	Keep this at `1` for production. This single setting prevents the LLM from accidentally walking an entire table.
`DDB_QUERY_MAX_LIMIT`	`500`	Hard cap on items per query	Queries are targeted (use a partition key), so cost is lower than scans. But a hot partition could still have thousands of items. `100`–`200` is safer for production.
`DDB_QUERY_DEFAULT_LIMIT`	`50`	Default items per query	Safety net for unparameterized queries.
`DDB_SAMPLE_MAX_N`	`20`	Max items returned by `sample_items`	Low risk — this is a schema discovery tool. Even at `20`, cost is negligible.
`DDB_BATCH_CHUNK_SIZE`	`100`	Keys per `BatchGetItem` API call	Matches the DynamoDB service maximum. Lowering this adds round-trips without saving cost. Leave at `100` unless you need to reduce per-request throughput spikes on provisioned tables.
`DDB_BATCH_MAX_RETRIES`	`10`	Max retries for `UnprocessedKeys`	Only relevant under throttling. On provisioned-capacity tables, aggressive retries can amplify throttle pressure. On on-demand tables, this rarely triggers.
`DDB_SHOW_COST`	`false`	When `true`, each data-plane tool response includes a `consumed_capacity` field with exact RCUs reported by DynamoDB	Zero overhead when disabled. When enabled, uses DynamoDB's native `ReturnConsumedCapacity` — no extra API calls, no estimation. Covers `get_item`, `batch_get_item`, `query`, `scan`, and `sample_items`. Control-plane tools (`list_tables`, `describe_table`, `get_indexes`) are always free and never report capacity.
`DDB_MAX_ITEMS_PER_SESSION`	`0` (unlimited)	Cumulative cap on total items returned across all tool calls in a server session	Prevents data exfiltration by bounding how much data can be extracted before a server restart. Set to `500`–`2000` for production. Once exceeded, all data-plane calls return an error until the server is restarted.
`DDB_MAX_CALLS_PER_MINUTE`	`0` (unlimited)	Max tool calls allowed per rolling 60-second window	Prevents rapid-fire automated extraction. Applies to all 8 tools. Rejected calls return a `RateLimitExceeded` error. Set to `30`–`60` for production.
`DDB_AUDIT_LOG`	`false`	When `true`, every tool call is logged to stderr with timestamp, tool name, table, and item count	Enables post-incident investigation and real-time monitoring. Logs go to stderr so they don't interfere with MCP's stdio transport. Pair with a log aggregator in HTTP mode.
`DDB_ALLOWED_TABLES`	(empty = all)	Comma-separated list of allowed table names/patterns (supports `*` globs)	App-level table restriction independent of IAM. `list_tables` only returns matching tables; all other tools reject non-matching tables. Examples: `dev-`, `dev-UserProfiles,dev-Orders`, `dev-,staging-*`.
`DDB_MAX_RESPONSE_BYTES`	`0` (unlimited)	Cap the serialized JSON size of a single tool response	Prevents a few very large items (DynamoDB allows up to 400 KB/item) from token-bombing the LLM context window. When exceeded, `items` are progressively dropped and a `truncated` flag is added. For `get_item` (single item, no list), an error is returned instead. Set to `500000`–`1000000` for production.
`DDB_READ_TIMEOUT`	`10` (seconds)	boto3 read timeout for every DynamoDB API call	Prevents slow or hung queries from tying up server resources (DoS vector in HTTP mode). A `ReadTimeoutError` is caught by the existing error handler and returned cleanly. Lower to `5` in latency-sensitive deployments; raise to `30` if scanning very large pages.

#### Quick cost reference

Scenario	RCUs consumed	Approximate cost
Scan 50 items × 1 KB (1 page, default settings)	~13	$0.000003
Scan 500 items × 1 KB (1 page, max limit)	~125	$0.00003
Scan 500 items × 20 pages × 1 KB (max everything)	~2,500	$0.0006
Full table scan of 1M items × 1 KB	~250,000	$0.06
Query 50 items × 1 KB	~13	$0.000003
BatchGetItem 100 items × 1 KB	~25	$0.000006

Costs shown are for eventually consistent reads at $0.25 per million RCUs (on-demand pricing, us-east-2). Strongly consistent reads cost 2×.

Beyond DynamoDB cost, large result sets also increase LLM token usage — 500 items serialized as JSON can easily exceed 50K tokens.

#### Example: tightened production config

{
  "mcpServers": {
    "ddb-explorer": {
      "command": "uvx",
      "args": ["ddb-explorer-mcp"],
      "env": {
        "AWS_PROFILE": "prod-readonly",
        "AWS_REGION": "us-east-2",
        "DDB_SCAN_DEFAULT_LIMIT": "20",
        "DDB_SCAN_MAX_LIMIT": "100",
        "DDB_SCAN_DEFAULT_MAX_PAGES": "1",
        "DDB_SCAN_MAX_PAGES": "3",
        "DDB_QUERY_MAX_LIMIT": "200",
        "DDB_SHOW_COST": "true",
        "DDB_MAX_ITEMS_PER_SESSION": "1000",
        "DDB_MAX_CALLS_PER_MINUTE": "30",
        "DDB_AUDIT_LOG": "true",
        "DDB_ALLOWED_TABLES": "prod-orders,prod-users,prod-events",
        "DDB_MAX_RESPONSE_BYTES": "500000",
        "DDB_READ_TIMEOUT": "10"
      }
    }
  }
}

HTTP-mode deployment

HTTP mode is for hosted / team scenarios. A single server instance serves many remote clients; the server holds the AWS credentials, clients don't.

What the server does NOT provide

TLS — terminate at a reverse proxy (nginx, Caddy, ALB, CloudFront)
Authentication — enforce at the proxy (Basic auth, JWT, mTLS, API Gateway + IAM, OAuth2)
Rate limiting — handle at the proxy or a sidecar

Recommended production shape

Internet ──► ALB (TLS + OIDC/JWT)
             │
             └─► ECS Fargate task
                   Image: ghcr.io/mudassirgithub/ddb-explorer-mcp:latest
                   Env:   MCP_TRANSPORT=http, MCP_HOST=0.0.0.0
                   IAM:   task role with read-only DynamoDB policy

A ready-to-use docker-compose.yml is available in examples/.

Minimal IAM policy for the server's AWS identity

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dynamodb:DescribeTable",
        "dynamodb:DescribeTimeToLive",
        "dynamodb:GetItem",
        "dynamodb:BatchGetItem",
        "dynamodb:Query",
        "dynamodb:Scan",
        "dynamodb:ListTables"
      ],
      "Resource": "*"
    }
  ]
}

For extra isolation, scope Resource to specific table ARNs.

Quick local HTTP test

MCP_TRANSPORT=http MCP_PORT=8765 uvx ddb-explorer-mcp

Then in another terminal:

curl -i http://127.0.0.1:8765/mcp
# Expect HTTP 406 — endpoint is live; MCP needs proper JSON-RPC POST + Accept.

Connect an MCP client pointing at http://127.0.0.1:8765/mcp to actually exercise it.

Security model

Read-only by construction. No write tools are registered with the MCP server.

This is a structural property, not a runtime flag.

No tool masquerading. Tool signatures are fixed; the server does not

dynamically execute arbitrary DynamoDB API calls on behalf of the LLM.

Scan safety. scan defaults to max_pages=1 (one page only). Hard cap 20 pages.

query paginates internally with a limit; hard-capped at 500 items per call. All caps are configurable via environment variables — see Safety limits.

Session item cap. DDB_MAX_ITEMS_PER_SESSION bounds the total items a single

server session can return across all tool calls. Once exceeded, all data-plane calls are rejected until the server is restarted. Prevents automated exfiltration loops.

Rate limiting. DDB_MAX_CALLS_PER_MINUTE enforces a sliding-window call

rate across all tools. Prevents rapid-fire extraction or accidental runaway loops.

Table allowlist. DDB_ALLOWED_TABLES restricts which tables the server can

access, independent of IAM permissions. Supports glob patterns (e.g. dev-*). list_tables only returns matching tables; all other tools reject non-matching ones.

Audit logging. DDB_AUDIT_LOG=true logs every tool call to stderr with

timestamp, tool name, table, and item count. Useful for monitoring and post-incident investigation, especially in HTTP mode with a log aggregator.

Response size cap. DDB_MAX_RESPONSE_BYTES limits the serialized JSON size

of any single tool response. Large items (DynamoDB allows up to 400 KB each) can overwhelm the LLM context window and spike token costs. When exceeded, items are progressively dropped and a truncated flag is set.

DynamoDB call timeout. DDB_READ_TIMEOUT (default 10 s) prevents slow or

hung queries from tying up server resources. Applies to every boto3 call via botocore.config.Config. Timeout errors are caught and returned cleanly.

No credential exposure to the LLM. Credentials live in the server process's

environment or IAM role. The LLM sees tool results, never config.

Prompt injection risk. DynamoDB items are user-generated data. A malicious

item could contain text designed to influence LLM behavior (e.g. "ignore previous instructions and..."). This is inherent to any system that feeds untrusted data into an LLM. Mitigations: restrict table access via DDB_ALLOWED_TABLES to trusted tables, enable human-in-the-loop approval for tool calls in your MCP client, and review DDB_AUDIT_LOG output for unexpected access patterns.

HTTP mode isolation. In HTTP mode (MCP_TRANSPORT=http), rate limits

(DDB_MAX_CALLS_PER_MINUTE) and session caps (DDB_MAX_ITEMS_PER_SESSION) are per-server-process, not per-client. One client's usage counts against all clients sharing the same server instance. For multi-tenant isolation, run separate server instances per client/team, or proxy through an API gateway that enforces per-client quotas. The server's internal counters are thread-safe but intentionally shared to provide a global safety net.

Defense in depth. Even with the above guarantees, you should still attach

the server's AWS identity to a read-only DynamoDB IAM policy. Never give it write or admin permissions, ever. Scope Resource in the IAM policy to specific table ARNs for maximum isolation.

Development

git clone https://github.com/mudassirgithub/ddb-explorer-mcp.git
cd ddb-explorer-mcp
make setup   # one-time: installs Python + deps

make test    # run the full test suite
make check   # lint + format-check + tests (same as CI)
make run     # start the server in stdio mode

Or without make:

uv sync --extra dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run ddb-explorer-mcp

Contributing

Contributions welcome — see CONTRIBUTING.md.

Code of Conduct

This project follows the Contributor Covenant.

Security

To report a security vulnerability, see SECURITY.md. Please do not open public issues for security matters.

License

Apache License 2.0 — see LICENSE.

Trademark notice

This project is not affiliated with, endorsed by, or sponsored by Amazon Web Services, Inc. "AWS" and "Amazon DynamoDB" are trademarks of Amazon.com, Inc. or its affiliates.

.vscode— mcp server

Is .vscode safe to install?

ddb-explorer-mcp

One-click install

Why ddb-explorer-mcp?

Installation

For end users (individual, stdio mode)

From a local clone

For teams (hosted HTTP mode)

Client configuration

Cursor

Claude Desktop

Claude Code CLI

VS Code (with Cline, Continue, or native MCP)

Windsurf

Remote HTTP (any client)

Tools reference

Example prompts

Configuration

AWS credentials / region

Transport

Safety limits

HTTP-mode deployment

What the server does NOT provide

Recommended production shape

Minimal IAM policy for the server's AWS identity

Quick local HTTP test

Security model

Development

Contributing

Code of Conduct

Security

License

Trademark notice

Audit the pieces. Scan the whole. Decide.