YugabyteDB MCP Server

An MCP server implementation for YugabyteDB that allows LLMs to directly interact with your database.

Features

• List all tables in the database, including schema and row counts
• Run read-only SQL queries and return results as JSON
• Designed for use with FastMCP and compatible with MCP clients like Claude Desktop, Cursor, and Windsurf Editor

Prerequisites

• Python 3.10 or higher
• uv installed to manage and run the server
• A running YugabyteDB database
• An MCP client such as Claude Desktop or Cursor

Installation

Clone this repository and install dependencies:

git clone git@github.com:yugabyte/yugabytedb-mcp-server.git
cd yugabytedb-mcp-server
uv sync

Configuration

The server is configured using the following:

| Environment Variable | Argument | Optional | Description | |----------------------|----------|----------|-------------| | YUGABYTEDB_URL | --yugabytedb-url | No | Connection string for your YugabyteDB database (e.g., dbname=database_name host=hostname port=5433 user=username password=password) | | YB_MCP_TRANSPORT | --transport | Yes | Transport protocol to use: stdio or http (default: stdio) | | YB_MCP_STATELESS_HTTP | --stateless-http| Yes | Enable stateless Streamable-HTTP mode: true or false (default: false) | | YB_AWS_SSL_ROOT_CERT_SECRET_ARN | --yb-aws-ssl-root-cert-secret-arn | Yes | ARN of the AWS Secrets Manager secret containing the TLS root certificate | | YB_AWS_SSL_ROOT_CERT_KEY | --yb-aws-ssl-root-cert-key | Yes | Key inside the secret JSON that selects which certificate to use | | YB_SSL_ROOT_CERT_PATH | --yb-ssl-root-cert-path | Yes | Filesystem path where the root certificate will be written (default: /tmp/yb-root.crt) | | YB_AWS_SSL_ROOT_CERT_SECRET_REGION | --yb-aws-ssl-root-cert-secret-region | Yes | Region of the AWS Secrets Manager secret containing the TLS root certificate |

Usage

Running the Server

You can run the server with STDIO transport using uv:

uv run src/server.py

or with stateful Streamable-HTTP transport:

uv run src/server.py --transport http

or with stateless Streamable-HTTP transport:

uv run src/server.py --transport http --stateless-http

Running the Server with Docker

Build the Docker image:

docker build -t mcp/yugabytedb .

Run the container with STDIO transport:

docker run -p 8000:8000 -e YUGABYTEDB_URL="your-db-url" mcp/yugabytedb

or with Streamable-HTTP transport:

Stateful Server:

docker run -p 8000:8000 \
  -e YUGABYTEDB_URL="your-db-url" \
  mcp/yugabytedb --transport=http

Stateless Server:

docker run -p 8000:8000 \
  -e YUGABYTEDB_URL="your-db-url" \
  -e YB_MCP_TRANSPORT=http \
  -e YB_MCP_STATELESS_HTTP=true \
  mcp/yugabytedb

Stateless Server with SSL enabled cluster:

docker run -p 8000:8000 \
  -v /path/to/root.crt:/certs/root.crt:ro \
  -e YUGABYTEDB_URL="your-db-url" \
  mcp/yugabytedb \
  --transport=http \
  --stateless-http

Running with TLS Certificates from AWS Secrets Manager

If your YugabyteDB cluster has TLS enabled and its root certificate is stored in AWS Secrets Manager, the MCP server can automatically fetch and configure it.

Plaintext secret (PEM stored directly)

The secret value contains the PEM certificate itself.

docker run -p 8000:8000 \
  -e YUGABYTEDB_URL="host=... port=5433 dbname=... user=... password=... sslmode=verify-full" \
  -e YB_MCP_TRANSPORT=http \
  -e YB_MCP_STATELESS_HTTP=true \
  -e YB_AWS_SSL_ROOT_CERT_SECRET_ARN=arn:ofthe:secret:manager \
  -e YB_AWS_SSL_ROOT_CERT_SECRET_REGION=region-of-the-secret-manager \
  -e AWS_ACCESS_KEY_ID="XXX" \
  -e AWS_SECRET_ACCESS_KEY="XXX" \


... [View full README on GitHub](https://github.com/yugabyte/yugabytedb-mcp-server#readme)