home / mcp / cockroachdb mcp server

Cockroachdb MCP Server

Provides direct MCP access to CockroachDB for Cursor with table discovery, schema inspection, SQL execution, and status resources.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "swayingleaves-cockroachdb-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/local/cockroachdb-mcp",
        "run",
        "server.py"
      ]
    }
  }
}

You can connect Cursor to a CockroachDB instance through an MCP (Model Context Protocol) server. This enables you to query databases, inspect table schemas, run SQL statements, and monitor status from Cursor with automatic reconnection and keep-alive features for stable, long-running sessions.

How to use

To use this MCP server, you configure it in your MCP client and start the server. You can connect to your CockroachDB instance, fetch all tables, inspect table structures, execute SQL queries, and access status and templates to assist you in building queries. The server handles automatic reconnection and keeps connections alive to minimize timeouts, and logs detailed information for troubleshooting.

How to install

# Prerequisites
- Install Python 3.8+ on your system
- Install Node.js and npm if you plan to use the Smithery flow
- Ensure curl is available for shell scripts

# 1) Install via Smithery (automatic on Claude Desktop)

npx -y @smithery/cli install @Swayingleaves/cockroachdb-mcp-server --client claude

# 2) Manual setup steps

# Clone the project (if you are working with a local copy)
# git clone https://example.com/swayingleaves/cockroachdb-mcp-server.git
# cd cockroachdb-mcp-server

# Install Python dependencies
pip install -r requirements.txt

# Install uv runtime (for running the server)
curl -LsSf https://astral.sh/uv/install.sh | sh
```

The installation steps above show both the automatic installer flow and the required manual steps to prepare the environment and runtime for the CockroachDB MCP Server.

Configuration and usage notes

The server is designed to connect directly to CockroachDB and expose a set of MCP methods to your Cursor client. The main features include an automatic reconnection mechanism and a keep-alive strategy to prevent idle-timeouts. Logs are written to a file for troubleshooting, and the server gracefully handles process exit.

Typical runtime configuration uses a stdio-based MCP entry that starts the server process via a local runtime (here, uv) with a path to the server script. You will provide the JDBC URL, username, and password for CockroachDB in the MCP configuration to establish the connection.

Note the logging path and keep-alive settings described below to monitor health and stability.

Troubleshooting and notes

If you encounter issues, check the server logs at logs/cockroachdb_mcp.log. The log file uses a rotating mechanism to cap disk usage, with 5 backups and a maximum size per file.

Common problems include connection refusals (ensure CockroachDB is running and reachable), authentication failures (verify credentials), and timeouts (check network stability, especially for remote databases). If the server is connected but you need to verify status, use the provided status resource to confirm connection state and version.

Resources and status

The MCP provides a status resource that reports the database connection state. When connected, it shows the connection is active along with the database version. If there is a connection error, it reports the error message for quick diagnosis.

SQL templates and queries

A built-in SQL query template helps you craft queries quickly. Use the template as a starting point for common tasks like listing tables, inspecting schemas, and executing ad-hoc queries.

Database actions you can perform

Connect to CockroachDB, initialize the connection, disconnect from the database manually, retrieve the list of tables, fetch a table’s schema, and execute arbitrary SQL queries. These actions map to MCP tools that you call from Cursor to interact with your CockroachDB instance.

Server logs and keep-alive details

Logs are stored at logs/cockroachdb_mcp.log with rotation settings to keep up to 5 backups and a maximum size of 10MB per file. TCP keep-alive is enabled to prevent timeouts during idle periods; keepalives_idle is 30, keepalives_interval is 10, and keepalives_count is 5.

Security considerations

Credentials for CockroachDB are provided in the MCP configuration (jdbc_url, username, password). The server uses psycopg2 to connect directly, which handles special characters in credentials without additional encoding. Treat credentials as sensitive information and manage them using your client’s secure secret storage.

Available tools

connect_database

Connect to CockroachDB database using JDBC URL, username, and password.

initialize_connection

Initialize the database connection after connecting to the MCP server to establish a working CockroachDB connection.

disconnect_database

Manually disconnect from the CockroachDB database.

get_tables

Retrieve the list of all tables in the connected database.

get_table_schema

Retrieve structure information for a specific table.

execute_query

Execute a SQL query against CockroachDB.

db://status

Provide a resource that returns the current database connection status.

sql_query_template

Provide a template to help you construct SQL queries.