CockroachDB MCP Server
Description
# CockroachDB MCP Server [](https://smithery.ai/server/@Swayingleaves/cockroachdb-mcp-server) [English](README.md) | [简体中文](README_zh.md) This is a CockroachDB MCP server for Cursor, implemented…
About
# CockroachDB MCP Server [](https://smithery.ai/server/@Swayingleaves/cockroachdb-mcp-server) [English](README.md) | [简体中文](README_zh.md) This is a CockroachDB MCP server for Cursor, implemented based on the Model Context Protocol (MCP)…
Details
- Author
- Swayingleaves
- Downloads
- 169
- Categories
- Database, Other
Jump to
- Connect to and disconnect from CockroachDB databases.
- Retrieve all tables and table schema information.
- Execute SQL queries directly.
- Provide database status resources and SQL query templates.
- Automatic reconnection and TCP keep-alive mechanisms.
- Detailed rotating logs for troubleshooting.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
CockroachDB MCP ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install dependencies with pip install -r requirements.txt and install uv via the official install script. Configure the server in Cursor by adding a JSON entry under mcpServers with the command uv, its arguments pointing to the server directory, and the JDBC URL, username, and password. The server can then be used through Cursor's MCP integration.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"cockroachdb mcp server": {
"cockroachdb-mcp-server-swayingleaves": {
"command": "npx",
"args": [
"-y",
"@smithery/cli",
"install",
"@Swayingleaves/cockroachdb-mcp-server",
"--client",
"claude"
]
}
}
}
}McpServers
{
"cockroachdb-mcp-server-swayingleaves": {
"command": "npx",
"args": [
"-y",
"@smithery/cli",
"install",
"@Swayingleaves/cockroachdb-mcp-server",
"--client",
"claude"
]
}
}CockroachDB MCP Server
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.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
