yugabytedb

This MCP server exposes a focused interface for interacting with a YugabyteDB instance via the Model Context Protocol. It supports listing all tables with schema and row counts, and running read-only SQL queries with results returned in JSON format. Intended to work with MCP clients like Claude Desktop, Cursor, and Windsurf Editor, you can connect to your YugabyteDB instance by configuring an MCP server entry in your client with the uv command and pointing it at this server implementation. Use the provided YUGABYTEDB_URL environment variable to supply the database connection details, and choose a transport mode (stdio by default, with optional http-based streams).

To use the server, start it through uv with the appropriate environment variable for your database. Once running, you can issue MCP requests to list tables, or submit read-only SQL queries. The server handles read-only access and returns results as JSON, making it straightforward to integrate with LLM workflows that need structured data from YugabyteDB.

Prerequisites:

• Python 3.10 or higher
• uv installed (for running the server via uv)
• A running YugabyteDB instance
• An MCP client (e.g., Claude Desktop, Cursor, Windsurf) to interact with the MCP server

Installation steps:

1. Clone the repository git clone git@github.com:yugabyte/yugabytedb-mcp-server.git cd yugabytedb-mcp-server

2. Install Python dependencies (if a virtual environment is used) python -m venv venv source venv/bin/activate pip install -r requirements.txt

3. Ensure uv is available to run the server. If not installed, install it per the uv documentation. pip install uv

4. Prepare environment variables for your database connection as needed. At minimum, set YUGABYTEDB_URL to your YugabyteDB connection string.

5. Run the server using uv (example): uv run src/server.py

Optional/docker alternative:

• Build and run a Docker container with the same environment variables and network configuration as described in the repository documentation.

Notes and tips:

• The server expects YUGABYTEDB_URL in the environment to connect to YugabyteDB. Use a connection string like: dbname=database_name host=hostname port=5433 user=username password=password.
• You can enable different MCP transports: stdio (default), or http-based transports by passing --transport http to uv run.
• For secure deployments, consider using TLS/SSL settings on the YugabyteDB side and configure the appropriate transport and SSL options in your MCP client.
• When using Docker, you can pass environment variables with -e keys and mount certificates if needed for TLS.
• If you encounter connection or credentials issues, verify network access between the MCP server and YugabyteDB and confirm the correct port in the URL string.