YugabyteDB MCP Server

The YugabyteDB MCP Server is a lightweight, Python-based server that enables LLMs such as Anthropic's Claude to securely connect to and query YugabyteDB. It supports the Model Context Protocol (MCP), an industry standard that allows AI tools to discover and use structured services like databases, file systems, or APIs.

With the YugabyteDB MCP Server, developers can:

• Explore YugabyteDB data using natural language prompts
• Generate AI-powered visualizations from query results
• Enable LLMs to safely issue read-only SQL queries (and optionally guarded writes)
• Map authenticated users to database roles via OIDC identity mapping
• Integrate instantly with AI coding agents such as Claude Desktop, Cursor, and Windsurf

YugabyteDB Agent Skills

Complement the MCP server with YugabyteDB Agent Skills. These are structured skill packages that give AI coding agents native YugabyteDB expertise for schema design, API usage, operations, and RAG workflows.

Install all skills at once:

npx skills add yugabyte/yugabytedb-skills

Or install individual skills (ysql, ycql, yb-k8s-operator, yba-api, yb-rag-langchain):

npx skills add yugabyte/yugabytedb-skills -s ysql

See the yugabytedb-skills repository for the full skill list and descriptions.

MCP tools

The server exposes three tools that MCP clients can call:

All three tools accept an optional requested_role parameter. When OIDC is enabled and the caller's identity claim resolves to multiple mapped database roles (for example, Cognito groups or Keycloak realm roles), the agent can pass requested_role to pick one. The server clamps the choice to the JWT's mapped candidates; the agent cannot SET ROLE to a role that is not in the token.

Claude Desktop surfaces read-only badges on the read tools and a confirmation prompt before each run_write_query call (destructiveHint: true).

Set up YugabyteDB MCP Server

Installing the server requires the following:

• Python 3.10+
• uv (recommended) or pip / pipx

Install and run the server using one of the following options.

Option 1: uvx (no install)

uvx yugabytedb-mcp-server --help

Option 2: Install the package

pipx install yugabytedb-mcp-server
# or: uv tool install yugabytedb-mcp-server
# or: pip install yugabytedb-mcp-server

yugabytedb-mcp --help

Option 3: From source (development)

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

OIDC and per-user database roles

For shared or remote deployments (HTTP transport), you can enable OIDC (AWS Cognito or a generic OIDC provider) so each authenticated caller runs SQL under their own YugabyteDB role via SET ROLE.

Using identity mapping, you can map usernames and group names authenticated via OIDC to roles in the YugabyteDB database. This way, OIDC usernames and groups don't need to be an exact match for role names in the YugabyteDB database. For example, you can map a username yng in Okta (via a regular expression match) to a YugabyteDB database role yng_role. When the OIDC user yng logs in, the user inherits the permissions associated with the mapped yng_role role.

Identity mapping mirrors YSQL native OIDC role mapping (ysql_ident_conf_csv / jwt_matching_claim_key):

When YB_MCP_IDENTITY_MAP is set, unmapped claim values are rejected (IdentityError) — the map is the allowlist. JWT audience validation is always on for Cognito and OIDC.

For full provider setup, map file format, worked examples (Cognito, Keycloak, Azure AD), and a migration checklist, see OIDC.md in the YugabyteDB MCP server repository.

Example: Claude Desktop

This tutorial walks you through using the YugabyteDB MCP Server to allow an AI application to access, query, analyze, and interpret data in your YugabyteDB database, using only natural language prompts.

The tutorial uses a YugabyteDB cluster running the Northwind dataset. You connect Claude to this database using MCP, and then explore it using natural language prompts.

Prerequisites

• YugabyteDB v2025.2 or later
• Claude Desktop

Set up YugabyteDB

1. Download and install YugabyteDB v2025.2 or later.

2. Start a single-node cluster using yugabyted.

   ./bin/yugabyted start --advertise_address=127.0.0.1
   

3. Install the Northwind sample database.

Connect Claude to the server

1. In Claude Desktop, navigate to Settings > Developer > Edit Config.

2. Add a new mcpServers entry in the claude_desktop_config.json.

   Via uvx (no install):

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

   Via an installed script (after pipx install or uv tool install):

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

   Replace the database user and password as appropriate.

   Configuration file locations:

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

3. Restart Claude to apply changes.

The same configuration works with Cursor (Settings > MCP) and Windsurf (Settings > Cascade > MCP Servers).

Prompt 1: Summarize the database

Prompt:

Summarize the database you are connected to.

Claude does the following:

• Calls summarize_database.
• Lists all tables with schema and row counts.
• Describes what it sees in plain English.

Example output:

This appears to be the classic Northwind database, a sample database
commonly used for demos and tutorials. Here's a summary:

Database Overview
This is a typical e-commerce/trading company database with 14 tables
and approximately 3,400 total rows of data.

Core Business Tables:

- orders (830 rows) - Customer orders with shipping details
- order_details (2,155 rows) - Line items for each order with pricing and quantities
- products (77 rows) - Product catalog with pricing and inventory
- customers (91 rows) - Customer information and contact details
- categories (8 rows) - Product categories

Supporting Tables:

- employees (9 rows) - Employee information including hierarchy (reports_to)
- suppliers (29 rows) - Product suppliers
- shippers (6 rows) - Shipping companies
- territories (53 rows) - Sales territories
- region (4 rows) - Geographic regions
- us_states (51 rows) - US state reference data

Junction Tables:

- employee_territories (49 rows) - Maps employees to territories
- customer_demographics (0 rows) - Empty demographic data
- customer_customer_demo (0 rows) - Empty customer-demographic mapping

This database supports typical business operations like order management,
inventory tracking, employee territories, and supplier relationships. Would
you like me to run any specific queries or analysis on this data?

Prompt 2: Build a dashboard

Prompt:

Build a dashboard with 3 visualizations:

- Monthly sales trend
- Top 10 customers by revenue
- Sales grouped by customer country

Claude does the following:

• Calls run_read_only_query with safe, read-only SQL.
• Aggregates and structures the results.
• Creates an interactive dashboard for the results.

All with no SQL required.

Example output:

I've created an interactive sales dashboard with all three visualizations you requested:

1. Monthly Sales Trend - A line chart showing revenue progression from July 1996 to
May 1998. You can see a clear upward trend with revenue growing from ~$27k to peaks
of ~$123k per month.
2. Top 10 Customers by Revenue - A horizontal bar chart showing QUICK-Stop, Ernst
Handel, and Save-a-lot Markets as the top three customers, each generating over $100k
in revenue.
3. Sales by Country - A scrollable horizontal bar chart displaying all 21 countries,
with USA and Germany leading at $245k and $230k respectively.

The dashboard features:

- Interactive tooltips showing exact values when you hover over data points
- Clean, modern design with a professional color scheme
- Responsive layout that adapts to different screen sizes
- Currency formatting for easy readability

All data is pulled directly from your Northwind database and shows real sales patterns
over the ~2-year period covered by the dataset.

Read more

• YugabyteDB MCP Server repository
• OIDC authentication and identity mapping
• Unlock AI-Driven Data Experiences with YugabyteDB MCP Server on AWS Marketplace
• Architecting GenAI and RAG Apps with YugabyteDB