Labsco
yugabyte logo

YugabyteDB MCP Server

★ 8

from yugabyte

Allows LLMs to directly interact with a YugabyteDB database.

🔥🔥🔥🔥✓ VerifiedFreeAdvanced setup
#email#automation#database#cloud#devops#git#maps#security

YugabyteDB MCP Server

An MCP server 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.

Features

  • summarize_database — list tables with columns and row counts for a schema (read-only)
  • run_read_only_query — execute a SELECT under BEGIN 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-query or YB_MCP_ENABLE_WRITE_QUERY=true)

Defense in depth: the write tool is annotated destructiveHint: 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.

Other MCP Clients

The same approach works with Cursor (Settings → MCP → Add a new global MCP server) and Windsurf (Settings → Cascade → MCP Servers → Add custom server) — use either the uvx form 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

Tools

ToolTitleHintsWhat it does
summarize_database(schema='public')"Summarize database schema and row counts"readOnlyHint: trueLists tables in schema with columns and row counts
run_read_only_query(query)"Run a read-only SQL query"readOnlyHint: trueWraps the query in BEGIN READ ONLY and returns rows as JSON
run_write_query(query)"Run a write SQL query (with guardrails)"destructiveHint: trueValidates the query against the guardrail blocklist, then executes. Disabled by default — requires --enable-write-query.

Guardrails for run_write_query

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
  • Filesystem / code execution: COPY TO/FROM, LOAD, anonymous DO $$ … $$, 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)
  • psql meta-commands (\c, \d, \!)
  • INSERT … VALUES over YB_MCP_MAX_INSERT_ROWS
  • Optionally UPDATE / DELETE without a WHERE clause

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

Self-hosted remote mode

For multi-user or shared deployments, run the server as Streamable HTTP behind a reverse proxy with TLS, with Cognito OAuth gating access:

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

Behavior:

  • Requests to /mcp without a valid Bearer token return 401.
  • Requests with a disallowed Origin header return 403 (DNS-rebinding defense).
  • /ping is unauthenticated and is suitable for liveness probes.
  • /auth/login exposes a Cognito email+password → token shortcut (see below).
  • --stateless-http is required for multi-replica deployments — without it, MCP session state lives in process memory and round-robin load balancing breaks sessions.

Getting a token without a browser

The browser-based OAuth flow is what Claude Desktop / mcp-remote / claude.ai use, but for curl-based smoke tests, CI, or any scripted client, the HTTP transport also exposes a direct password endpoint when MCP_AUTH_PROVIDER=cognito:

curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"…"}'
# →
# {"access_token":"…","id_token":"…","refresh_token":"…","expires_in":86400,"token_type":"Bearer"}

Then:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H "Accept: application/json,text/event-stream" \
     -X POST http://localhost:8000/mcp \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

The endpoint uses Cognito's USER_PASSWORD_AUTH flow under the hood — the Cognito app client must have ALLOW_USER_PASSWORD_AUTH enabled (Cognito Console → User pools → App integration → App client settings). MFA, password-reset, and other challenge flows are not handled by this endpoint — they require the browser flow.

OIDC (MCP_AUTH_PROVIDER=oidc) wiring exists but is untested; please share findings if you exercise it.

Per-user database roles (SET ROLE)

When OIDC auth is enabled, the server can map each authenticated user to a YugabyteDB database role using SET ROLE. This enforces row-level security, schema-level grants, and per-user privilege boundaries — the same connection pool is used, but each tool call runs under the caller's database role.

export YB_MCP_IDENTITY_CLAIM=email             # JWT claim to extract (default)
export YB_MCP_IDENTITY_TRANSFORM=strip_domain  # alice@example.com → alice

How it works:

  1. The server extracts the configured claim from the OIDC access token.
  2. An optional transform derives the DB role name (e.g., stripping @domain).
  3. Before executing tool SQL, the server issues SET ROLE <role> on the pooled connection.
  4. After execution, RESET ROLE restores the connection to the pool user.

Requirements:

  • The pool user (from YUGABYTEDB_URL) must be a superuser or have GRANT <target_role> TO <pool_user> for every role that can authenticate.
  • Target roles must already exist in the database — the server does not create them.
  • When auth is disabled (no MCP_AUTH_PROVIDER), SET ROLE is not used and the pool operates with its configured credentials as before.

Example setup:

-- Create per-user roles matching the identity claim
CREATE ROLE alice LOGIN;
CREATE ROLE bob LOGIN;

-- Grant them to the pool user so SET ROLE works
GRANT alice TO mcp_admin;
GRANT bob TO mcp_admin;

-- Apply per-role permissions as needed
GRANT SELECT ON ALL TABLES IN SCHEMA public TO alice;
GRANT ALL ON ALL TABLES IN SCHEMA public TO bob;

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 (set YB_AWS_SSL_ROOT_CERT_KEY to 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

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

Security

  • All SQL is run through parameterized queries; user input is never interpolated into statement strings.
  • The write tool is disabled by default — must be explicitly enabled with --enable-write-query.
  • The write tool's guardrail list (above) blocks the highest-risk statement classes.
  • destructiveHint: true ensures Claude Desktop surfaces a per-call confirmation for write operations.
  • When OIDC auth is active, per-user SET ROLE enforces database-level privilege boundaries per caller. Role names are safely quoted with psycopg.sql.Identifier.
  • HTTP transport requires a valid Bearer token when MCP_AUTH_PROVIDER is configured.
  • HTTP transport validates the Origin header against MCP_ALLOWED_ORIGINS (defaults to MCP_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 for run_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.

Privacy Policy

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 by YB_LOG_LEVEL) — no remote log aggregation is built in.

Development

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

Note: there is no longer a src/server.py you can run directly. The package layout was reorganized for PyPI distribution (entry point + namespace) so the modules now live under src/yugabytedb_mcp_server/. Always invoke via the yugabytedb-mcp console script (registered by uv sync / pip install) — running the module file with python would skip the package import machinery and break the relative imports.

Equivalent commands:

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. After uv sync, the yugabytedb-mcp script is on your $PATH (via the active venv). Add this to your claude_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 .mcpb and 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 .mcpb into Claude Desktop — the connector installer UI takes it from there, prompting for the user_config values defined in manifest.json. The .mcpb route is closest to what reviewers will exercise. Note: the manifest's mcp_config runs uvx yugabytedb-mcp-server, which fetches the package from PyPI on first launch. Make sure the version referenced by your .mcpb is published before sharing the bundle.

Testing

# 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.md for the coverage table and the manual Cognito smoke recipe.