YugabyteDB MCP server

The YugabyteDB MCP Server allows LLMs to directly interact with your YugabyteDB database, enabling capabilities such as listing tables and running read-only SQL queries. It's compatible with various MCP clients like Claude Desktop, Cursor, and Windsurf Editor.

Prerequisites

• Python 3.10 or higher
• uv package manager
• A running YugabyteDB database
• An MCP client such as Claude Desktop or Cursor

Installation

Clone the repository and install dependencies:

git clone [email protected]:yugabyte/yugabytedb-mcp-server.git
cd yugabytedb-mcp-server
uv sync

Configuration

Configure the server using the following environment variable:

• YUGABYTEDB_URL: Your YugabyteDB connection string

Example .env file:

YUGABYTEDB_URL=postgresql://user:password@localhost:5433/yugabyte

Running the Server

Using uv

Run with STDIO transport:

uv run src/server.py

Or with Streamable-HTTP transport:

uv run src/server.py --transport http

Using Docker

Build the Docker image:

docker build -t mcp/yugabytedb .

Run with STDIO transport:

docker run -p 8080:8080 -e YUGABYTEDB_URL="your-db-url" mcp/yugabytedb

Or with Streamable-HTTP transport:

docker run -p 8080:8080 -e YUGABYTEDB_URL="your-db-url" mcp/yugabytedb --transport=http

Configuring MCP Clients

Claude Desktop

1. Go to Claude → Settings → Developer → Edit Config
2. Add the following configuration under mcpServers:

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

For Docker configuration:

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

3. Restart Claude Desktop

Cursor

1. Go to Cursor > Settings > Cursor Settings > MCP > Add a new global MCP server
2. Add the same configuration as shown above
3. Save the configuration
4. Verify the server appears in the MCP servers list and is enabled

Windsurf Editor

1. Go to Windsurf > Settings > Windsurf Settings > Cascade > Model Context Protocol (MCP) Servers > Add server > Add custom server
2. Add the configuration as shown above
3. Save and refresh

Using Streamable-HTTP with MCP Inspector

1. Start the server with HTTP transport:

   uv run src/server.py --transport http
   

2. Launch the inspector:

   npx @modelcontextprotocol/inspector
   

3. Configure with:

   • URL: http://localhost:8080/invocations/mcp
   • Transport type: Streamable-HTTP
   • Add the proxy token from terminal output

Available Tools

The MCP server provides two main tools:

• summarize_database: Lists all tables with their schemas and row counts
• run_read_only_query: Executes a read-only SQL query and returns results as JSON

Troubleshooting

• Verify the YUGABYTEDB_URL is correct
• Ensure your database is accessible
• Check that your user has appropriate permissions
• If Claude cannot access uv (error: spawn uv ENOENT), create a symlink:

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

• Check logs in your MCP client for connection errors:
  • MacOS: ~/Library/Logs/Claude
  • Windows: %APPDATA%\Claude\Logs
  • Cursor: Select "Cursor MCP" from the Output panel dropdown

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "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"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect