YugabyteDB MCP Server

Get LLMs to interact directly with YugabyteDB

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
Integrate instantly with tools like Claude Desktop, Cursor, and Windsurf

For more information about the YugabyteDB MCP Server, see Unlock AI-Driven Data Experiences with YugabyteDB MCP Server.

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.1 or later (stable), or v2.25.1 or later (preview)
Python 3.10+
uv for dependency management
Claude Desktop

Set up YugabyteDB MCP Server

Clone the repo and install dependencies:

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

Set up YugabyteDB

Download and install YugabyteDB v2025.1 or later (stable), or v2.25.1 or later (preview).

Start a single-node cluster using yugabyted.

./bin/yugabyted start --advertise_address=127.0.0.1

Install the Northwind sample database.

Connect Claude to the server

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

Add a new mcpServer entry in the claude_desktop_config.json:

{
    "mcpServers": {
        "yugabytedb-mcp": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/cloned/yugabytedb-mcp-server/",
                "run",
                "src/server.py"
            ],
            "env": {
                "YUGABYTEDB_URL": "dbname=northwind host=localhost port=5433 user=yugabyte password=yugabyte"
            }
        }
    }
}

Replace the path, and database user and password as appropriate.

Restart Claude to apply changes.

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