Dhartunian Cockroachdb MCP Server

🚀 CockroachDB Management Control Plane (MCP) Server

This MCP server connects to a CockroachDB instance, exposes database and table schemas as resources, runs SQL queries as tools, and provides query analysis hints.

🚀 Quick Start

This MCP server offers seamless integration with CockroachDB, enabling users to access database resources and execute SQL queries efficiently.

✨ Features

Resources

• postgres://{host}/databases/{database} - Retrieve information about a specific database.
• postgres://{host}/databases/{database}/tables/{table}/schema - Obtain the schema of a specific table.
• postgres://{host}/cluster-metadata/{resource} - Fetch cluster metadata (requires an authentication token).
  • Currently supported: nodes - Information about cluster nodes.

Tools

• query - Execute SQL queries with an option for execution plan analysis.

📦 Installation

1. Clone this repository.
2. Install dependencies:

   pnpm install
   

3. Build the project:

   npx tsc
   

⚠️ Important Note

Before using the MCP server locally, you must build it using tsc.

📚 Documentation

Configuration

The server requires a database URL as a command-line argument and optionally accepts an authentication token to access the management console endpoints:

node dist/server.js postgres://user:password@host:port/database [auth_token]

The authentication token is used to access cluster metadata resources.

Using Claude for Desktop

1. Open your Claude for Desktop application configuration:

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

2. Add your server configuration:

{
  "mcpServers": {
    "cockroachdb": {
      "command": "node",
      "args": [
        "/path/to/cockroachdb-mcp-server/dist/server.js", 
        "postgres://user:password@host:port/database",
        "your_auth_token"
      ]
    }
  }
}

3. Restart Claude for Desktop.

Using Cline

1. Open your Cline configuration file (find "MCP Server" from the extension settings). Select "Configure MCP Server".
2. Add your server configuration:

{
  "mcpServers": {
    "crdb": {
      "command": "node",
      "args": [
        "/path/to/cockroachdb-mcp-server/dist/server.js",
        "postgres://root@127.0.0.1:26257/testdb",
        "your_auth_token"
      ]
    }
  }
}

3. Restart Cline or start a new session.

Example Queries

Here are some example questions you can ask Claude:

1. "What databases are in my CockroachDB instance?"
2. "Can you show the schema of the 'users' table in the 'testdb' database?"
3. "Run this query: SELECT * FROM users LIMIT 10"
4. "Debug this query and suggest improvements: SELECT * FROM orders WHERE customer_id = 123"
5. "Show information about all CockroachDB cluster nodes"

Security Considerations

⚠️ Important Note

• Be cautious when configuring database access. If you only need to query data, consider using a read-only user.
• The authentication token is used to access the CockroachDB management console API. Ensure that you keep this token secure.

Troubleshooting

💡 Usage Tip

• If you encounter connection issues, check your database credentials and ensure that the CockroachDB instance is accessible.
• Verify that the configuration file is correct, especially the paths and parameter locations.
• Check if there are any firewall or network restrictions preventing access to the database instance.