YugabyteDB MCP Server

by yugabyte

214 downloads

Not rated

GitHub

About

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

Details

Author: yugabyte
Downloads: 214
Categories: Database, Other

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name YugabyteDB MCP Server

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "yugabytedb mcp server": {
            "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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "yugabytedb mcp server": {
            "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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "yugabytedb mcp server": {
            "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"
                }
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "yugabytedb mcp server": {
            "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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "yugabytedb mcp server": {
            "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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "yugabytedb mcp server": {
            "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"
                }
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "yugabytedb mcp server": {
            "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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "yugabytedb mcp server": {
            "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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "yugabytedb mcp server": {
            "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"
                }
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "yugabytedb mcp server": {
            "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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "yugabytedb mcp server": {
            "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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "yugabytedb mcp server": {
            "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"
                }
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "yugabytedb mcp server": {
            "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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "yugabytedb mcp server": {
            "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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "yugabytedb mcp server": {
            "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"
                }
            }
        }
    }
}

From the repository

Install by cloning the repository and running uv sync. Set the YUGABYTEDB_URL environment variable with your database connection string, then start the server with uv run server.py. Configure your MCP client (e.g., Claude Desktop, Cursor, Windsurf Editor) by adding a server entry using uv as the command and specifying the environment variable.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "yugabytedb mcp server": {
            "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"
                }
            }
        }
    }
}

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"
        }
    }
}

Allows LLMs to directly interact with a YugabyteDB database.

AnMCPserver for YugabyteDB and PostgreSQL — lets LLMs (Claude Desktop, Cursor, Windsurf, etc.) summarize schemas, run read-only queries, and execute write statements behind a configurable guardrail layer.

- summarize_database— list tables with columns and row counts for a schema (read-only)
- run_read_only_query— execute a SELECT underBEGIN READ ONLY; results returned as JSON (read-only)
- run_write_query— INSERT/UPDATE/DELETE/MERGE/TRUNCATE/DDL gated by a guardrail blocklist (destructive,disabled by default— enable with--enable-write-queryorYB_MCP_ENABLE_WRITE_QUERY=true)

Defense in depth: the write tool is annotateddestructiveHint: true, so Claude Desktop surfaces a confirmation prompt before every call even when the guardrails would let the statement through.

Optional OAuth (AWS Cognito) and Origin-header validation for self-hosted remote deployments.

- Python 3.10+
- uv(recommended) or pip
- A reachable YugabyteDB or PostgreSQL database
- An MCP client (Claude Desktop, Cursor, Windsurf, etc.)

Three install options, in roughly the order of how end users will reach for them:

# uvx — no install at all; fetches and runs on demand. Handy for one-off use # and also the form the MCPB Desktop extension uses internally. uvx yugabytedb-mcp-server --help # pipx — installs to an isolated venv, puts the script on $PATH. pipx install yugabytedb-mcp-server # uv tool — same idea, uv-managed. uv tool install yugabytedb-mcp-server # pip — system-level or current-venv install. pip install yugabytedb-mcp-server

After any of the persistent installs (pipx / uv tool / pip), verify with:

yugabytedb-mcp --help # or, equivalently: yugabytedb-mcp-server --help

Both console scripts are registered and point at the same entry point —yugabytedb-mcpis the short form,yugabytedb-mcp-servermatches the package name and is whatuvxresolves to by default.

Pre-release note: while v2 is in release-candidate (e.g.2.0.0rc2), default installs won't pick it up. For now, install with an explicit version (pipx install yugabytedb-mcp-server==2.0.0rc2) or with--pip-args='--pre'. This goes away once2.0.0stable is published.

For development from source, see Developmentbelow.

For OIDC/Cognito authentication, per-userSET ROLEmapping, the identity map file format, and the/auth/loginshortcut — see OIDC.md.

Two ways to wire it up. The first usesuvxand requires no install at all —uvonly. The second assumes you've already runpipx install(or equivalent) and have theyugabytedb-mcpscript on$PATH.

{ "mcpServers": { "yugabytedb": { "command": "uvx", "args": ["yugabytedb-mcp-server"], "env": { "YUGABYTEDB_URL": "host=… port=5433 dbname=… user=… password=…" } } } }

Afterpipx install yugabytedb-mcp-server(oruv tool install …):

{ "mcpServers": { "yugabytedb": { "command": "yugabytedb-mcp", "env": { "YUGABYTEDB_URL": "host=… port=5433 dbname=… user=… password=…" } } } }

Locations ofclaude_desktop_config.json:

- macOS:~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:%APPDATA%\Claude\claude_desktop_config.json

Restart Claude Desktop. The three tools will appear with titles and hint badges (read-only icons on the read tools, a confirmation prompt before eachrun_write_querycall).

While2.0.0rc2is the only published version, theuvxsnippet needs["yugabytedb-mcp-server@2.0.0rc2"]in the args (or["--pre", "yugabytedb-mcp-server"]). Drop the explicit version once2.0.0stable is out.

The same approach works withCursor(Settings → MCP → Add a new global MCP server) andWindsurf(Settings → Cascade → MCP Servers → Add custom server) — use either theuvxform or the installed-script form from above.

For MCP Inspector against an HTTP-mode server:

YUGABYTEDB_URL="…" yugabytedb-mcp --transport http # in another shell: npx @modelcontextprotocol/inspector # In the GUI: URL http://localhost:8000/mcp, transport Streamable-HTTP

The following statement classes are rejected before execution:

- DROP DATABASE/SCHEMA,ALTER DATABASE,CREATE DATABASE
- Role/privilege ops:GRANT,REVOKE,CREATE/ALTER/DROP ROLE,CREATE/ALTER/DROP USER
- Stored code that can run under the owner (SECURITY DEFINER):CREATE FUNCTION,CREATE PROCEDURE,ALTER FUNCTION,ALTER PROCEDURE
- Filesystem / code execution:COPY TO/FROM,LOAD, anonymousDO $$ … $$,CREATE EXTENSION
- Server config:ALTER SYSTEM,RESET ALL
- Dangerous built-ins:pg_sleep,pg_read_file,pg_write_file,lo_import,lo_export,dblink
- Schema isolation:SET search_path,CREATE SCHEMA
- Multi-statement queries (anything with a separator semicolon)
- psqlmeta-commands (\c,\d,\!)
- INSERT … SELECT(unbounded row source;YB_MCP_MAX_INSERT_ROWSonly capsINSERT … VALUES)
- INSERT … VALUES overYB_MCP_MAX_INSERT_ROWS
- Optionally UPDATE / DELETE without a WHERE clause

CREATE TABLE … AS SELECTandSELECT … INTOare structurally similar unbounded row copies but are intentionallyallowed— they're the common way to materialize a snapshot from a query.

This list is best-effort, not exhaustive.destructiveHint: trueis the second line of defense.

For multi-user or shared deployments, run the server as Streamable HTTP behind a reverse proxy with TLS, with Cognito OAuth (or generic OIDC) gating access. The full setup — provider config, per-userSET ROLEmapping, the identity map file format, the/auth/loginshortcut, and security guidance — is inOIDC.md.

Secure-by-default:since the DB-22139 fix, HTTP mode binds127.0.0.1by default andrefuses to startwhen both of these are true:

- The bind host is non-loopback (MCP_HOSTset to0.0.0.0or a specific address)
- No auth provider is configured (MCP_AUTH_PROVIDERunset)

For a shared / networked deployment, set bothMCP_HOST=0.0.0.0andMCP_AUTH_PROVIDER:

export MCP_HOST=0.0.0.0 # expose beyond loopback (default: 127.0.0.1) export MCP_AUTH_PROVIDER=cognito export MCP_BASE_URL=https://mcp.example.com export COGNITO_USER_POOL_ID=us-west-2_XXXXXXXX export COGNITO_AWS_REGION=us-west-2 export COGNITO_CLIENT_ID=… export COGNITO_CLIENT_SECRET=… export YUGABYTEDB_URL=… export MCP_ALLOWED_ORIGINS=https://mcp.example.com,https://claude.ai yugabytedb-mcp --transport http --stateless-http

Fordev-only unauthenticateduse on0.0.0.0, setMCP_ALLOW_UNAUTHENTICATED=true— the server starts with a prominent WARNING. Do not use this in production.

- Requests to/mcpwithout a valid Bearer token return 401.
- Requests with a disallowedOriginheader return 403 (DNS-rebinding defense).
- /pingis unauthenticated and is suitable for liveness probes.
- /auth/loginexposes a Cognito email+password → token shortcut (details in OIDC.md).
- --stateless-httpis required for multi-replica deployments — without it, MCP session state lives in process memory and round-robin load balancing breaks sessions.

AWS Secrets Manager for TLS certificates

If your database TLS root certificate is stored in AWS Secrets Manager, the server can fetch and use it automatically. Plaintext PEM is supported; JSON-keyed bundles too (setYB_AWS_SSL_ROOT_CERT_KEYto pick one).

yugabytedb-mcp \ --yugabytedb-url "host=… port=5433 dbname=… user=… password=… sslmode=verify-full" \ --yb-aws-ssl-root-cert-secret-arn arn:aws:secretsmanager:us-east-1:…:secret:my-cert \ --yb-aws-ssl-root-cert-secret-region us-east-1

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

- All SQL is run through parameterized queries; user input is never interpolated into statement strings.
- The write tool isdisabled by default— must be explicitly enabled with--enable-write-query.
- The write tool's guardrail list (above) blocks the highest-risk statement classes.
- destructiveHint: trueensures Claude Desktop surfaces a per-call confirmation for write operations.
- When OIDC auth is active, per-userSET ROLEenforces database-level privilege boundaries per caller. Role names are safely quoted withpsycopg.sql.Identifier.
- HTTP transport requires a valid Bearer token whenMCP_AUTH_PROVIDERis configured.
- HTTP transport validates theOriginheader againstMCP_ALLOWED_ORIGINS(defaults toMCP_BASE_URL).
- HTTPS is the operator's responsibility — terminate TLS at a reverse proxy (nginx, ALB, etc.) in front of the server.
- Run with a least-privilege database role (read-only role forrun_read_only_query-only deployments; otherwise a role scoped to the target schemas, no superuser).

Report security issues privately to support@yugabyte.com— please do not open public GitHub issues for vulnerabilities.

Yugabyte's privacy policy applies:https://www.yugabyte.com/privacy-policy/

This MCP server does not transmit telemetry. All database access stays between Claude (your MCP client) and your YugabyteDB instance via the connection string you provide. The server logs locally to stderr (controlled byYB_LOG_LEVEL) — no remote log aggregation is built in.

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

Note: there isno longer asrc/server.pyyou can run directly. The package layout was reorganized for PyPI distribution (entry point + namespace) so the modules now live undersrc/yugabytedb_mcp_server/. Always invoke via theyugabytedb-mcpconsole script (registered byuv sync/pip install) — running the module file withpythonwould skip the package import machinery and break the relative imports.

uv run yugabytedb-mcp # uses the console script uv run python -m yugabytedb_mcp_server # uses the __main__.py shim

Testing the connector locally in Claude Desktop

Two paths, depending on how close to the production install experience you want to get:

Fastest — no MCPB build, just point Claude Desktop at the local entry point. Afteruv sync, theyugabytedb-mcpscript is on your$PATH(via the active venv). Add this to yourclaude_desktop_config.json:

{ "mcpServers": { "yugabytedb-dev": { "command": "/absolute/path/to/repo/.venv/bin/yugabytedb-mcp", "env": { "YUGABYTEDB_URL": "host=localhost port=5433 dbname=yugabyte user=yugabyte password=yugabyte", "YB_LOG_LEVEL": "DEBUG" } } } }

Restart Claude Desktop. Use~/Library/Logs/Claude/mcp-server-yugabytedb-dev.log(macOS) to inspect debug output. This skips the MCPB bundling entirely and is the right loop for iterating on tool code.

Closer to production — build a.mcpband drag it into Claude Desktop. Requires the MCPB CLI:

npm install -g @modelcontextprotocol/mcpb-cli # one-time mcpb validate manifest.json # static check mcpb pack . # produces yugabytedb-mcp-server-<version>.mcpb

Drag the resulting.mcpbinto Claude Desktop — the connector installer UI takes it from there, prompting for theuser_configvalues defined inmanifest.json. The.mcpbroute is closest to what reviewers will exercise.Note: the manifest'smcp_configrunsuvx yugabytedb-mcp-server, which fetches the package from PyPI on first launch. Make sure the version referenced by your.mcpbis published before sharing the bundle.

# unit tests (no DB, no network) uv run pytest tests/test_guardrails.py tests/test_auth.py tests/test_identity_mapping.py # integration tests (require a reachable Postgres-compatible DB) YUGABYTEDB_URL="host=… port=… …" uv run pytest tests/

See tests/README.mdfor the coverage table and the manual Cognito smoke recipe.

- spawn yugabytedb-mcp ENOENTfrom Claude Desktop → ensure the install directory is on the PATH Claude Desktop sees;pipx ensurepathor symlink the entry point into/usr/local/bin.
- Tools list is empty in the MCP client → restart the client; checkYB_LOG_LEVEL=DEBUGoutput for connection errors during lifespan.
- "Invalid or expired transaction" / "Client Not Registered" in HTTP+OAuth mode with multiple replicas → see the self-hosted remote section;--stateless-httpis mandatory for multi-replica.

Multi-database agent access (PostgreSQL, SQLite, MySQL, Oracle, SQL Server) with batch queries, pre-configured connections, and SQLGlot-enforced read-only safety

A read-only MCP server for querying AWS PostgreSQL databases.

A read-only MCP server for AlloyDB, enabling LLMs to query live data directly from AlloyDB databases.

A read-only MCP server by CData that enables LLMs to query live data from EnterpriseDB databases.

A server for direct interaction with CockroachDB databases.

Database MCP server for MySQL, MariaDB, PostgreSQL & SQLite

A single-binary MCP server for MySQL, MariaDB, PostgreSQL, and SQLite

A Model Context Protocol (MCP) server that provides multi-database query execution capabilities with support for SQLite, PostgreSQL, and MySQL databases. Includes a built-in Web UI for managing database connections.

Update various databases (PostgreSQL, MySQL, MongoDB, SQLite) using data from CSV and Excel files.

Expert-level PostgreSQL database analysis MCP server for AI assistants.

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

Claude Desktop / Cursor

McpServers

AWS Secrets Manager for TLS certificates

Testing the connector locally in Claude Desktop

Install

More like this

Sequential Thinking

Redis

Filesystem

EverArt

Google Drive

Sqlite