npm package: @mihnea.dev/cassandra-mcp
Description: MCP server for Apache Cassandra over SSH — gives Claude Code direct CQL access
Latest version: 1.0.0

# @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

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

## Claude Code Setup

Add to `~/.claude.json`:

```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):

```json
{
  "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):

```bash
# 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

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