CockroachDB MCP Server

How to use

You will run a local MCP server that connects to CockroachDB through the CData JDBC Driver. Start the server and point clients to the MCP entry points. Use your MCP client to invoke the tools to explore tables, inspect columns, and run read-only queries. You can simply ask questions like, “What is the total revenue by region last quarter?” or “Show open opportunities by account.” The server handles translating your requests into safe, SQL-backed reads and returns results in a structured format.

How to install

Prerequisites: Install a Java runtime environment and a Java build tool since you will compile and run a Java-based MCP server.

Step 1. Build the MCP server jar from source.

# Clone the project
git clone https://github.com/cdatasoftware/cockroachdb-mcp-server-by-cdata.git
cd cockroachdb-mcp-server-by-cdata

# Build the server (Maven is required)
mvn clean install

Additional setup steps

Step 2. Install the CData JDBC Driver for CockroachDB from the official download page.

Step 3. License the JDBC Driver using the provided jar and license flow.

Step 4. Configure your JDBC connection and generate a .prp file that will be used by the MCP server to connect to CockroachDB.

Step 5. Prepare a Claude/Desktop-compatible config pointing to the MCP server (for local testing you can wire this to your preferred MCP client). Ensure the config references the MCP runtime jar and your .prp file.

Running the server

You run the MCP server as a local process that reads a .prp connection file. The server operates in stdio mode, which allows a local client to communicate directly on the same machine.

# Example start command (replace paths with your actual locations)
java -jar /PATH/TO/CDataMCP-jar-with-dependencies.jar /PATH/TO/cockroachdb.prp

Configuration example

Use this as a concrete snippet to configure the MCP server for CockroachDB. It assumes a local, read-only setup connected via a JDBC driver and a .prp file named cockroachdb.prp.

{
  "mcpServers": {
    "cockroachdb_mcp_win": {
      "type": "stdio",
      "name": "cockroachdb_mcp_win",
      "command": "java",
      "args": [
        "-jar",
        "PATH\\TO\\CDataMCP-jar-with-dependencies.jar",
        "PATH\\TO\\cockroachdb.prp"
      ]
    },
    "cockroachdb_mcp_unix": {
      "type": "stdio",
      "name": "cockroachdb_mcp_unix",
      "command": "/PATH/TO/java",
      "args": [
        "-jar",
        "/PATH/TO/CDataMCP-jar-with-dependencies.jar",
        "/PATH/TO/cockroachdb.prp"
      ]
    }
  }
}

Troubleshooting

If the MCP server does not appear in your client, ensure you have fully exited and restarted the client so it reloads available servers. Verify the .prp file contains the correct JDBC connection string and that the Java runtime can access the required JAR files.

If data cannot be retrieved, re-check the JDBC connection settings and test the connection using the JDBC driver’s utility. Validate that the server process started correctly and is emitting logs that confirm a successful data source connection.

Notes and security

This MCP server is read-only by design to provide safe access to live CockroachDB data. Ensure you limit the MCP server exposure to trusted clients and consider network-level access controls to prevent unauthorized querying.

Keep your JDBC driver and server jar up to date to benefit from the latest compatibility and security improvements.

Tools and endpoints overview

The server exposes tools to list tables, list columns, and run read-only queries. Use these tools to discover data schemas and retrieve results for analysis.

cockroachdb_get_tables

Retrieves a list of tables available in the CockroachDB data source. The output is provided in CSV format with a header line of column names.

cockroachdb_get_columns

Retrieves a list of columns for a specified table. The output is provided in CSV format with a header line of column names.

cockroachdb_run_query

Executes a SQL SELECT query against CockroachDB and returns the results.