Metadata-Version: 2.4
Name: awslabs.documentdb-mcp-server
Version: 1.0.12
Summary: An AWS Labs Model Context Protocol (MCP) server for documentdb
Project-URL: homepage, https://awslabs.github.io/mcp/
Project-URL: docs, https://awslabs.github.io/mcp/servers/documentdb-mcp-server/
Project-URL: documentation, https://awslabs.github.io/mcp/servers/documentdb-mcp-server/
Project-URL: repository, https://github.com/awslabs/mcp.git
Project-URL: changelog, https://github.com/awslabs/mcp/blob/main/src/documentdb-mcp-server/CHANGELOG.md
Author: Amazon Web Services
Author-email: AWSLabs MCP <203918161+awslabs-mcp@users.noreply.github.com>, Nitin Ahuja <nitahuja@amazon.com>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: loguru>=0.7.0
Requires-Dist: mcp[cli]>=1.23.0
Requires-Dist: pydantic>=2.10.6
Requires-Dist: pymongo>=4.12.1
Description-Content-Type: text/markdown

# 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 connect to and query AWS DocumentDB databases. It serves as a bridge between AI assistants and AWS DocumentDB, allowing for safe and efficient database operations through the Model Context Protocol (MCP).

## Features

- **Connection Management**: Establish and maintain connections to DocumentDB clusters
- **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:

### Connection Management

- `connect`: Connect to a DocumentDB cluster and get a connection ID
- `disconnect`: Close an active connection

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

```bash
# Basic usage
python -m awslabs.documentdb_mcp_server.server

# With custom port and host
python -m awslabs.documentdb_mcp_server.server --port 9000 --host 0.0.0.0

# With write operations enabled
python -m awslabs.documentdb_mcp_server.server --allow-write
```

### Command Line Options

| Option | Description | Default |
|--------|-------------|---------|
| `--log-level` | Set logging level (TRACE, DEBUG, INFO, etc.) | INFO |
| `--connection-timeout` | Idle connection timeout in minutes | 30 |
| `--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
- Connection management operations (`connect`, `disconnect`) work normally

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

### Basic Connection and Query (Read-Only Operations)

```python
# Connect to a DocumentDB cluster
connection_result = await use_mcp_tool(
    server_name="awslabs.aws-documentdb-mcp-server",
    tool_name="connect",
    arguments={
        "connection_string": "mongodb://<username>:<password>@docdb-cluster.cluster-xyz.us-west-2.docdb.amazonaws.com:27017/?tls=true&tlsCAFile=global-bundle.pem"
    }
)
connection_id = connection_result["connection_id"]

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

# Close the connection when done
await use_mcp_tool(
    server_name="awslabs.aws-documentdb-mcp-server",
    tool_name="disconnect",
    arguments={"connection_id": connection_id}
)
```

### Enabling Write Operations

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

```bash
python -m awslabs.documentdb_mcp_server.server --allow-write
```

When the server is running with write operations enabled:

```python
# This operation will succeed
query_result = await use_mcp_tool(
    server_name="awslabs.aws-documentdb-mcp-server",
    tool_name="find",
    arguments={
        "connection_id": connection_id,
        "database": "my_database",
        "collection": "users",
        "query": {"active": True}
    }
)

# 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={
        "connection_id": connection_id,
        "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 |
|:----:|:------:|:-------:|
| [![Add to Kiro](https://kiro.dev/images/add-to-kiro.svg)](https://kiro.dev/launch/mcp/add?name=awslabs.documentdb-mcp-server&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22awslabs.documentdb-mcp-server%40latest%22%5D%2C%22env%22%3A%7B%22FASTMCP_LOG_LEVEL%22%3A%22ERROR%22%2C%22AWS_PROFILE%22%3A%22your-aws-profile%22%7D%7D) | [![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/en/install-mcp?name=awslabs.documentdb-mcp-server&config=eyJjb21tYW5kIjoidXZ4IGF3c2xhYnMuZG9jdW1lbnRkYi1tY3Atc2VydmVyQGxhdGVzdCIsImVudiI6eyJGQVNUTUNQX0xPR19MRVZFTCI6IkVSUk9SIiwiQVdTX1BST0ZJTEUiOiJ5b3VyLWF3cy1wcm9maWxlIn0sImRpc2FibGVkIjpmYWxzZSwiYXV0b0FwcHJvdmUiOltdfQ==) | [![Install on VS Code](https://img.shields.io/badge/Install_on-VS_Code-FF9900?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=DocumentDB%20MCP%20Server&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22awslabs.documentdb-mcp-server%40latest%22%5D%2C%22env%22%3A%7B%22FASTMCP_LOG_LEVEL%22%3A%22ERROR%22%2C%22AWS_PROFILE%22%3A%22your-aws-profile%22%7D%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D) |

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

```json
{
  "mcpServers": {
    "awslabs.documentdb-mcp-server": {
      "command": "uvx",
      "args": [
        "awslabs.documentdb-mcp-server@latest",
      ],
      "env": {
        "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:

```json
{
  "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": {
        "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`)
