What is Cockroachdb Mcp Server

The cockroachdb-mcp-server is a server that connects to a CockroachDB instance, exposing database and table schemas as resources, executing SQL queries as tools, and providing prompts for query analysis.

Use cases

Use cases include querying available databases, retrieving specific table schemas, executing SQL queries, debugging queries, and obtaining information about cluster nodes.

How to use

To use the cockroachdb-mcp-server, clone the repository, install dependencies using ‘pnpm install’, build the project with ‘npx tsc’, and run the server with the database URL and optional auth token as command-line arguments.

Key features

Key features include accessing database information, retrieving table schemas, obtaining cluster metadata, and executing SQL queries with options for execution plan analysis.

Where to use

The cockroachdb-mcp-server can be used in various fields such as data analysis, application development, and database management where CockroachDB is utilized.

CockroachDB MCP Server

This MCP server connects to a CockroachDB instance, exposing database and table schemas as resources, running SQL queries as tools, and providing prompts for query analysis.

Features

Resources

• postgres://{host}/databases/{database} - Get information about a specific database
• postgres://{host}/databases/{database}/tables/{table}/schema - Get the schema for a specific table
• postgres://{host}/cluster-metadata/{resource} - Get cluster metadata (requires auth token)
  • Currently supports: nodes - Information about cluster nodes

Tools

• query - Execute a SQL query with options for execution plan analysis

Installation

1. Clone this repository
2. Install dependencies:

   pnpm install
   

3. Build the project:

   npx tsc
   

Note: You must build the project with tsc before using the MCP server locally.

Configuration

The server requires a database URL as a command-line argument and optionally accepts an auth token for accessing admin UI endpoints:

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

The auth token is required for accessing cluster metadata resources.

Using with Claude for Desktop

1. Open your Claude for Desktop App 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 with Cline

1. Open your Cline configuration file from the extension settings under “MCP Servers”. Select “Configure MCP Servers”.

2. Add your server configuration:

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

3. Restart Cline or start a new session

Example Queries

Here are some example queries you can ask Claude:

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

Security Considerations

• Be careful when configuring database access. Consider using a read-only user for the connection if you only need to query data.
• The auth token is used to access the CockroachDB admin UI API. Make sure to keep this token secure.

Troubleshooting

• If you encounter connection issues, verify your database credentials and ensure the CockroachDB instance is accessible from your machine.
• For SQL errors, check the server logs for detailed error messages.
• If Claude can’t see the server, verify the configuration file is properly formatted and the path to the server.js file is correct.
• For cluster metadata resources, ensure you’ve provided a valid auth token and that the admin UI is accessible on port 8080.