CockroachDB MCP Server

English | 简体中文

This is a CockroachDB MCP server for Cursor, implemented based on the Model Context Protocol (MCP) specification, allowing you to interact directly with CockroachDB database in Cursor.

Features

• Connect to CockroachDB database
• Get all tables from the database
• Get table structure information
• Execute SQL queries
• Provide database status resources
• Provide SQL query templates
• Automatic reconnection mechanism to ensure connection stability
• Connection keep-alive mechanism to prevent connection timeout
• Graceful process exit handling
• Detailed logging for troubleshooting
• Support manual disconnection

Installation

Installing via Smithery

To install CockroachDB MCP Server for Claude Desktop automatically via Smithery:

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

1. Clone the repository and enter the project directory
2. Install dependencies:

pip install -r requirements.txt

3. Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Using in Cursor

{
    "mcpServers": {
        "cockroachdb-mcp": {
            "command": "uv",
            "args": [
                "--directory",
                "/Users/local/cockroachdb-mcp",
                "run",
                "server.py"
            ],
            "jdbc_url": "jdbc:postgresql://localhost:26257/defaultdb",
            "username": "root",
            "password": "root"
        }
    }
  }

MCP Function Description

Tools

connect_database

Connect to CockroachDB database.

Parameters:

• jdbc_url: JDBC connection URL (e.g., jdbc:postgresql://localhost:26257/defaultdb)
• username: Database username
• password: Database password

initialize_connection

Initialize database connection, can be called immediately after connecting to the MCP server to establish a database connection.

Parameters:

• jdbc_url: JDBC connection URL (e.g., jdbc:postgresql://localhost:26257/defaultdb)
• username: Database username
• password: Database password

disconnect_database

Manually disconnect from the database.

No parameters.

get_tables

Get all tables from the database.

No parameters.

get_table_schema

Get structure information of a specified table.

Parameters:

• table_name: Table name

execute_query

Execute SQL query.

Parameters:

• query: SQL query statement

Resources

db://status

Get database connection status.

Returns:

• When not connected: "Not connected"
• When connected: "Connected - [Database version]"
• When connection error: "Connection error - [Error message]"

Prompts

sql_query_template

SQL query template to help users write SQL queries.

Logs

Server logs are saved in logs/cockroachdb_mcp.log file. You can check this file to understand the server's running status and detailed logs.

The log file uses a rotating log mechanism, with each log file maximum size of 10MB and keeping up to 5 backup files to prevent excessive disk space usage.

Special Character Handling

This server uses psycopg2 to connect directly to CockroachDB database, which automatically handles special characters in usernames and passwords without additional URL encoding. This ensures correct database connection even when passwords contain special characters (such as @, %, &, etc.).

TCP Keep-alive Settings

The server is configured with TCP keep-alive mechanism by default to prevent connections from being closed due to long periods of inactivity:

• keepalives=1: Enable TCP keepalive
• keepalives_idle=30: Send keepalive after 30 seconds of idle time
• keepalives_interval=10: Send keepalive every 10 seconds
• keepalives_count=5: Give up after 5 attempts

Troubleshooting

If you encounter problems, please check the log file logs/cockroachdb_mcp.log, which will help you understand the server's running status and potential issues.

Common Issues

1. Connection Refused: Ensure the CockroachDB server is running and accessible from your machine.
2. Authentication Failed: Check if the username and password are correct.
3. Connection Timeout: Check if the network connection is stable, especially when connecting to a remote database.
4. Database Server Issues: Check if the CockroachDB server is running properly.