@mihnea.dev/cassandra-mcp

MCP (Model Context Protocol) server for Apache Cassandra over SSH. Gives Claude Code direct access to Cassandra for AI-assisted data engineering workflows.

Install

npm install -g @mihnea.dev/cassandra-mcp

Claude Code Setup

Add to ~/.claude.json:

{
  "mcpServers": {
    "cassandra": {
      "command": "cassandra-mcp",
      "env": {
        "SSH_HOST": "your-ssh-jump-host",
        "SSH_USER": "your-ssh-user",
        "SSH_KEY_PATH": "/path/to/your/ssh/key",
        "CASSANDRA_REMOTE_HOST": "cassandra-host-behind-ssh",
        "CASSANDRA_REMOTE_PORT": "9042",
        "CASSANDRA_LOCAL_DATA_CENTER": "dc1",
        "CASSANDRA_CERTS_DIR": "/path/to/certs"
      }
    }
  }
}

Or run directly with npx (no install needed):

{
  "mcpServers": {
    "cassandra": {
      "command": "npx",
      "args": ["-y", "@mihnea.dev/cassandra-mcp"],
      "env": {
        "SSH_HOST": "your-ssh-jump-host",
        "SSH_USER": "your-ssh-user",
        "SSH_KEY_PATH": "/path/to/your/ssh/key",
        "CASSANDRA_REMOTE_HOST": "cassandra-host-behind-ssh",
        "CASSANDRA_REMOTE_PORT": "9042",
        "CASSANDRA_LOCAL_DATA_CENTER": "dc1",
        "CASSANDRA_CERTS_DIR": "/path/to/certs"
      }
    }
  }
}

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | SSH_HOST | Yes | — | SSH jump host address | | SSH_PORT | No | 22 | SSH port | | SSH_USER | Yes | — | SSH username | | SSH_KEY_PATH | Yes | — | Path to SSH private key | | CASSANDRA_REMOTE_HOST | Yes | — | Cassandra host behind SSH | | CASSANDRA_REMOTE_PORT | No | 9042 | Remote Cassandra port | | CASSANDRA_LOCAL_DATA_CENTER | No | dc1 | Cassandra datacenter name | | CASSANDRA_CERTS_DIR | No | — | Directory containing TLS certificates | | CASSANDRA_CA_CERT | No | $CASSANDRA_CERTS_DIR/ca-cert.pem | CA certificate path | | CASSANDRA_CLIENT_CERT | No | $CASSANDRA_CERTS_DIR/client-cert.pem | Client certificate path | | CASSANDRA_CLIENT_KEY | No | $CASSANDRA_CERTS_DIR/client-key.pem | Client private key path |

TLS Setup

If your Cassandra cluster requires mutual TLS (client certificate authentication), provide the certificate files via CASSANDRA_CERTS_DIR or the individual CASSANDRA_CA_CERT, CASSANDRA_CLIENT_CERT, and CASSANDRA_CLIENT_KEY variables.

To extract certificates from Java keystores (JKS):

# Convert keystore to PKCS12
keytool -importkeystore -srckeystore keystore.jks -srcstorepass <pass> \
  -destkeystore keystore.p12 -deststoretype PKCS12 -deststorepass <pass>

# Extract client cert and key
openssl pkcs12 -in keystore.p12 -passin pass:<pass> -nokeys -out client-cert.pem
openssl pkcs12 -in keystore.p12 -passin pass:<pass> -nocerts -nodes -out client-key.pem

# Extract CA from truststore
keytool -importkeystore -srckeystore truststore.jks -srcstorepass <pass> \
  -destkeystore truststore.p12 -deststoretype PKCS12 -deststorepass <pass>
openssl pkcs12 -in truststore.p12 -passin pass:<pass> -nokeys -out ca-cert.pem

Tools

| Tool | Description | |------|-------------| | cassandra_login | Authenticate with username/password. Establishes SSH tunnel and connects to the cluster. | | cassandra_execute | Execute a CQL query (SELECT, INSERT, UPDATE, DELETE, DDL) | | cassandra_get_keyspaces | List all keyspaces | | cassandra_get_tables | List tables in a keyspace | | cassandra_describe_table | Describe a table's schema (columns, types, keys) |

Development

git clone https://github.com/mihneamanolache/cassandra-mcp
cd cassandra-mcp
npm install
npm run build