Amazon DocumentDB MCP Server

AWS DocumentDB MCP Server

An AWS Labs Model Context Protocol (MCP) server for AWS DocumentDB that enables AI assistants to interact with DocumentDB databases.

Overview

The DocumentDB MCP Server provides tools to query a single AWS DocumentDB cluster. It serves as a bridge between AI assistants and AWS DocumentDB, allowing for safe and efficient database operations through the Model Context Protocol (MCP).

The target cluster is configured by the operator at server startup (via the --connection-string CLI argument or the DOCUMENTDB_CONNECTION_STRING environment variable). Tools operate on that configured cluster directly and take only database/collection/query arguments.

Features

Operator-configured connection: Connect to a single DocumentDB cluster fixed at startup
Database Management: List databases and retrieve database statistics
Collection Management: List, create, drop collections and retrieve collection statistics
Document Operations: Query, insert, update, and delete documents
Aggregation Pipelines: Execute DocumentDB aggregation pipelines
Query Planning: Get explanations of how operations will be executed
Schema Analysis: Analyze collection schemas by sampling documents
Read-Only Mode: Optional security feature to restrict operations to read-only operations

Available Tools

The DocumentDB MCP Server provides the following tools. All tools operate on the cluster configured at server startup and take only database/collection/query arguments (no connection string or connection id):

Database Management

listDatabases: List all available databases in the DocumentDB cluster
getDatabaseStats: Get statistics about a DocumentDB database

Collection Management

listCollections: List collections in a database
createCollection: Create a new collection in a database (blocked in read-only mode)
dropCollection: Drop a collection from a database (blocked in read-only mode)
getCollectionStats: Get statistics about a collection
countDocuments: Count documents in a collection
analyzeSchema: Analyze the schema of a collection by sampling documents and providing field coverage

Document Operations

find: Query documents from a collection
aggregate: Run aggregation pipelines (pipelines with $out or $merge stages are blocked in read-only mode)
insert: Insert documents (blocked in read-only mode)
update: Update documents (blocked in read-only mode)
delete: Delete documents (blocked in read-only mode)

Query Planning

explainOperation: Get an explanation of how an operation will be executed

Server Configuration

Starting the Server

The server requires a connection string for the DocumentDB cluster it should connect to, supplied via the DOCUMENTDB_CONNECTION_STRING environment variable (recommended) or the --connection-string argument. If no connection string is configured, database tools fail until one is set.

Prefer the environment variable: a connection string passed as a command-line argument is visible to other local users via process listings (e.g. ps), and the environment variable keeps the credentials out of argv. An MCP client configuration file that sets DOCUMENTDB_CONNECTION_STRING still holds the password, so restrict access to that file.

# Recommended: provide the connection string via environment variable
export DOCUMENTDB_CONNECTION_STRING="mongodb://<username>:<password>@docdb-cluster.cluster-xyz.us-west-2.docdb.amazonaws.com:27017/?tls=true&tlsCAFile=global-bundle.pem&retryWrites=false"
python -m awslabs.documentdb_mcp_server.server

# With write operations enabled
DOCUMENTDB_CONNECTION_STRING="mongodb://...&retryWrites=false" \
  python -m awslabs.documentdb_mcp_server.server --allow-write

# Convenience only: pass the connection string as an argument. Note that this
# exposes the connection string (including any password) in process listings;
# prefer DOCUMENTDB_CONNECTION_STRING instead.
python -m awslabs.documentdb_mcp_server.server \
  --connection-string "mongodb://<username>:<password>@docdb-cluster.cluster-xyz.us-west-2.docdb.amazonaws.com:27017/?tls=true&tlsCAFile=global-bundle.pem&retryWrites=false"

Command Line Options

Option	Description	Default
`--log-level`	Set logging level (TRACE, DEBUG, INFO, etc.)	INFO
`--connection-string`	DocumentDB connection string for the cluster to connect to. Prefer the `DOCUMENTDB_CONNECTION_STRING` environment variable, which keeps credentials out of process listings.	None
`--allow-write`	Enable write operations (otherwise defaults to read-only mode)	False

Read-Only Mode

By default, the server runs in read-only mode that only allows read operations. This enhances security by preventing any modifications to the database. In read-only mode:

Read operations (find, listCollections) work normally
Aggregation pipelines (aggregate) work normally, except pipelines containing $out or $merge stages are blocked
Write operations (insert, update, delete, createCollection, dropCollection) are blocked and return a permission error

This mode is particularly useful for:

Demonstration environments
Security-sensitive applications
Integration with public-facing AI assistants
Protecting production databases from unintended modifications

Usage Examples

The cluster is configured when the server is started (see Starting the Server). Tools operate on that configured cluster and do not take a connection string or connection id.

Basic Query (Read-Only Operations)

# Query documents on the configured cluster
query_result = await use_mcp_tool(
    server_name="awslabs.aws-documentdb-mcp-server",
    tool_name="find",
    arguments={
        "database": "my_database",
        "collection": "users",
        "query": {"active": True},
        "limit": 5
    }
)

Enabling Write Operations

To enable write operations, start the server with the --allow-write flag:

python -m awslabs.documentdb_mcp_server.server \
  --connection-string "mongodb://...&retryWrites=false" --allow-write

When the server is running with write operations enabled:

# This operation will now succeed when --allow-write is used
insert_result = await use_mcp_tool(
    server_name="awslabs.aws-documentdb-mcp-server",
    tool_name="insert",
    arguments={
        "database": "my_database",
        "collection": "users",
        "documents": {"name": "New User", "active": True}
    }
)

# Without the --allow-write flag, you would receive this error:
# ValueError: "Operation not permitted: Server is configured in read-only mode. Use --allow-write flag when starting the server to enable write operations."

Configure in your MCP client

Kiro	Cursor	VS Code

Configure the MCP server in your MCP client configuration (e.g., for Kiro, edit ~/.kiro/settings/mcp.json):

{
  "mcpServers": {
    "awslabs.documentdb-mcp-server": {
      "command": "uvx",
      "args": [
        "awslabs.documentdb-mcp-server@latest",
      ],
      "env": {
        "DOCUMENTDB_CONNECTION_STRING": "mongodb://<username>:<password>@docdb-cluster.cluster-xyz.us-west-2.docdb.amazonaws.com:27017/?tls=true&tlsCAFile=global-bundle.pem&retryWrites=false",
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1",
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Windows Installation

For Windows users, the MCP server configuration format is slightly different:

{
  "mcpServers": {
    "awslabs.documentdb-mcp-server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "awslabs.documentdb-mcp-server@latest",
        "awslabs.documentdb-mcp-server.exe"
      ],
      "env": {
        "DOCUMENTDB_CONNECTION_STRING": "mongodb://<username>:<password>@docdb-cluster.cluster-xyz.us-west-2.docdb.amazonaws.com:27017/?tls=true&tlsCAFile=global-bundle.pem&retryWrites=false",
        "FASTMCP_LOG_LEVEL": "ERROR",
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

Prerequisites

Network access to your DocumentDB cluster
SSL/TLS certificate if your cluster requires TLS (typically global-bundle.pem)

Overview​

Features​

Available Tools​

Database Management​

Collection Management​

Document Operations​

Query Planning​

Server Configuration​

Starting the Server​

Command Line Options​

Read-Only Mode​

Usage Examples​

Basic Query (Read-Only Operations)​

Enabling Write Operations​

Configure in your MCP client​

Windows Installation​

Prerequisites​