YugabyteDB MCP Server

Allows LLMs to directly interact with a YugabyteDB database.

GitHub

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" \
  -e AWS_SESSION_TOKEN="XXX" \
  mcp/yugabytedb

JSON secret (multiple certificates in one secret)

The secret value is JSON, for example:


{
  "cert-cluster-1": "-----BEGIN CERTIFICATE----- ...",
  "cert-cluster-2": "-----BEGIN CERTIFICATE----- ..."
}

Select which certificate to use:

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_KEY=cert-cluster-1 \
  -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" \
  -e AWS_SESSION_TOKEN="XXX" \
  mcp/yugabytedb

By default the certificate is written to /tmp/yb-root.crt. You can override this using:

-e YB_SSL_ROOT_CERT_PATH=/custom/path/root.crt

MCP Client Configuration

To use this server with an MCP client (e.g., Claude Desktop, Cursor), add it to your MCP client configuration.

Running via `uv`

Example configuration for Cursor:

{
  "mcpServers": {
    "yugabytedb-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/cloned/yugabytedb-mcp-server/",
        "run",
        "src/server.py"
      ],
      "env": {
        "YUGABYTEDB_URL": "dbname=database_name host=hostname port=5433 user=username password=password load_balance=true topology_keys=cloud.region.zone1,cloud.region.zone2"
      }
    }
  }
}

Replace /path/to/cloned/yugabytedb-mcp-server/ with the path to your cloned repository.
Set the correct database URL in the env section.

Running via Docker (e.g., in Claude)

After building the docker container, add the following to claude_config.json entry or equivalent json files for other editors:

{
  "mcpServers": {
    "yugabytedb-mcp-docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "YUGABYTEDB_URL=dbname=yugabyte host=host.docker.internal port=5433 user=yugabyte password=yugabyte load_balance=false",
        "mcp/yugabytedb"
      ]
    }
  }
}

Claude Desktop

Edit the configuration file. Go to Claude -> Settings -> Developer -> Edit Config
Add the above configuration under mcpServers.
Restart Claude Desktop.

Claude Desktop Logs

The logs for Claude Desktop can be found in the following locations:

MacOS: ~/Library/Logs/Claude
Windows: %APPDATA%\Claude\Logs

The logs can be used to diagnose connection issues or other problems with your MCP server configuration. For more details, refer to the official documentation.

Cursor

Install Cursor on your machine.
Go to Cursor > Settings > Cursor Settings > MCP > Add a new global MCP server.
Add the configuration as above.
Save the configuration.
You will see yugabytedb-mcp-server as an added server in MCP servers list. Refresh to see if server is enabled.

Cursor Logs

In the bottom panel of Cursor, click on "Output" and select "Cursor MCP" from the dropdown menu to view server logs. This can help diagnose connection issues or other problems with your MCP server configuration.

Windsurf Editor

Install Windsurf Editor on your machine.
Go to Windsurf > Settings > Windsurf Settings > Cascade > Model Context Protocol (MCP) Servers > Add server > Add custom server.
Add the configuration as above.
Save and refresh.

Streamable-HTTP with MCP Inspector

Start the server using Streamable-HTTP:

uv run src/server.py --transport http

Or with Docker:

docker run -p 8000:8000 -e YUGABYTEDB_URL="..." mcp/yugabytedb --transport=http

Launch the inspector:
```
npx @modelcontextprotocol/inspector
```
In the GUI, use the URL:
```
http://localhost:8000/mcp
```
- Change transport type to Streamable-HTTP
- Add the proxy token from the terminal output

Tools Provided

summarize_database: Lists all tables in the database, including schema and row counts.
run_read_only_query: Runs a read-only SQL query and returns the results as JSON.

Example Usage

Once connected via an MCP client, you can:

Ask for a summary of the database tables and schemas
Run SELECT queries and get results in JSON

Environment Variables

YUGABYTEDB_URL: (required) The connection string for your YugabyteDB/PostgreSQL database

Troubleshooting

Ensure the YUGABYTEDB_URL is set and correct
Verify your database is running and accessible
Check that your user has the necessary permissions
Make sure uv is installed and available in your PATH. Note: If claude is unable to access uv, giving the error: spawn uv ENOENT, try symlinking the uv for global access:

sudo ln -s "$(which uv)" /usr/local/bin/uv

Review logs in your MCP client for connection or query errors

Development

Project dependencies are managed in pyproject.toml
Main server logic is in src/server.py

Related Servers

Dataset Viewer

Interact with the Hugging Face Dataset Viewer API to browse, filter, and get statistics for datasets.

dbt-docs

MCP server for dbt-core (OSS) users as the official dbt MCP only supports dbt Cloud. Supports project metadata, model and column-level lineage and dbt documentation.

CData Adobe Analytics

A read-only MCP server to query live Adobe Analytics data. Requires the CData JDBC Driver for Adobe Analytics.

Adobe Commerce MCP Server by CData

A read-only MCP server for Adobe Commerce, enabling LLMs to query live data using the CData JDBC driver.

Python MSSQL MCP Server

A Python MCP server for Microsoft SQL Server, enabling schema inspection and SQL query execution.

Elasticsearch

Connect to and interact with an Elasticsearch cluster directly from any MCP client using environment variables for configuration.

Poland KRS

Access to Polish National Court Register (KRS) — the government's authoritative registry of all businesses, foundations, and other legal entities.

Tigris Data

A serverless NoSQL database and search platform.

MySQL MCP Server

Provides direct access to MySQL databases, allowing AI agents to execute SQL queries and manage database content.

CData eBay MCP Server

A read-only MCP server for querying live eBay data. Requires a separately licensed CData JDBC Driver for eBay.

YugabyteDB MCP Server

YugabyteDB MCP Server

Features

Prerequisites

Installation

Configuration

Usage

Running the Server

Running the Server with Docker

Running with TLS Certificates from AWS Secrets Manager

Plaintext secret (PEM stored directly)

JSON secret (multiple certificates in one secret)

MCP Client Configuration

Running via uv

Running via Docker (e.g., in Claude)

Claude Desktop

Claude Desktop Logs

Cursor

Cursor Logs

Windsurf Editor

Streamable-HTTP with MCP Inspector

Tools Provided

Example Usage

Environment Variables

Troubleshooting

Development

Related Servers

Dataset Viewer

dbt-docs

CData Adobe Analytics

Adobe Commerce MCP Server by CData

Python MSSQL MCP Server

Elasticsearch

Poland KRS

Tigris Data

MySQL MCP Server

CData eBay MCP Server

Running via `uv`