DataStax OpsCenter MCP Server

A Model Context Protocol (MCP) server that provides access to DataStax OpsCenter API for monitoring and managing Apache Cassandra and DataStax Enterprise clusters.

🚀 Features

This MCP server provides tools to:

• Cluster Management: Get cluster configurations and detailed information
• Metrics Collection: Retrieve performance metrics at cluster, node, and table levels
• Node Monitoring: Query individual node information and metrics
• Schema Information: Access keyspace and table schemas
• Event Tracking: Monitor cluster events and alerts
• Comprehensive Metrics: Support for 100+ metrics including:
  • Cluster metrics (read/write ops, latency, memory usage)
  • Thread pool metrics (pending/active tasks)
  • Table metrics (disk usage, SSTable counts, latency)
  • OS metrics (CPU, memory, disk, network)

📋 Prerequisites

• Node.js: Version 18.x, 20.x, or 22.x
• DataStax OpsCenter: Version 6.8.x or compatible
• Access: Network connectivity to your OpsCenter instance

� Documentation

• Cassandra Troubleshooting Guide - Comprehensive guide for production troubleshooting with 9-phase workflow, critical thresholds, and emergency procedures
• Metrics Coverage Analysis - Complete coverage report of all 340+ OpsCenter metrics
• Metrics Quick Reference - Fast lookup guide for metric names to MCP tools
• GitHub Copilot Instructions - Development guidelines and project architecture

�🔧 Installation

1. Clone the Repository

git clone https://github.com/yourusername/datastax-opscenter-mcp.git
cd datastax-opscenter-mcp

2. Install Dependencies

npm install

3. Build the Project

npm run build

This compiles TypeScript to JavaScript in the build/ directory.

⚙️ Configuration

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | OPSCENTER_URL | Yes | http://localhost:8888 | OpsCenter base URL | | OPSCENTER_USERNAME | No | - | Username for authentication (if enabled) | | OPSCENTER_PASSWORD | No | - | Password for authentication (if enabled) |

---

🔌 Setup for VS Code with GitHub Copilot

1. Locate Your VS Code MCP Settings File

macOS/Linux:

code ~/.vscode/mcp-settings.json

Windows:

code %APPDATA%\Code\User\mcp-settings.json

If the file doesn't exist, create it.

2. Add Server Configuration

Add the following to your mcp-settings.json:

{
  "mcpServers": {
    "datastax-opscenter": {
      "command": "node",
      "args": [
        "/absolute/path/to/datastax-opscenter-mcp/build/index.js"
      ],
      "env": {
        "OPSCENTER_URL": "http://your-opscenter-host:8888",
        "OPSCENTER_USERNAME": "your_username",
        "OPSCENTER_PASSWORD": "your_password"
      }
    }
  }
}

⚠️ Important:

• Replace /absolute/path/to/datastax-opscenter-mcp with the actual path where you cloned the repo
• Update OPSCENTER_URL, OPSCENTER_USERNAME, and OPSCENTER_PASSWORD with your values
• On Windows, use forward slashes or escaped backslashes in paths: C:/Users/YourName/datastax-opscenter-mcp/build/index.js

3. Restart VS Code

Close and reopen VS Code for the changes to take effect.

4. Verify Installation

1. Open GitHub Copilot Chat in VS Code
2. Type @datastax-opscenter and you should see the server available
3. Try a test command:

   @datastax-opscenter get_cluster_configs
   

---

🖥️ Setup for Claude Desktop

1. Locate Claude Desktop Configuration

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

2. Edit Configuration File

Open the configuration file and add the MCP server:

{
  "mcpServers": {
    "datastax-opscenter": {
      "command": "node",
      "args": [
        "/absolute/path/to/datastax-opscenter-mcp/build/index.js"
      ],
      "env": {
        "OPSCENTER_URL": "http://localhost:8888",
        "OPSCENTER_USERNAME": "admin",
        "OPSCENTER_PASSWORD": "password"
      }
    }
  }
}

⚠️ Configuration Notes:

• Use absolute paths for the args parameter
• Remove OPSCENTER_USERNAME and OPSCENTER_PASSWORD if your OpsCenter doesn't require authentication
• Update OPSCENTER_URL to match your OpsCenter instance

3. Restart Claude Desktop

Completely quit and restart the Claude Desktop application.

4. Verify Installation

In Claude Desktop, you should see the MCP server connected. Try:

Can you get the cluster configurations from OpsCenter?

---

🐳 Docker Setup (Optional)

If you prefer running the MCP server in a container:

1. Create Dockerfile

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

ENV OPSCENTER_URL=http://localhost:8888

CMD ["node", "build/index.js"]

2. Build and Run

docker build -t datastax-opscenter-mcp .

docker run -it \
  -e OPSCENTER_URL=http://your-opscenter:8888 \
  -e OPSCENTER_USERNAME=admin \
  -e OPSCENTER_PASSWORD=password \
  datastax-opscenter-mcp

---

📖 Quick Start Examples

Once configured, you can use the MCP server to monitor your Cassandra clusters:

Available Tools

Cluster Operations

get_cluster_configs

Get configuration information for all clusters managed by OpsCenter.

get_cluster_info

Get detailed information about a specific cluster.

• Parameters: cluster_id

get_nodes

Get list of all nodes in a cluster with their properties.

• Parameters: cluster_id
• Note: Returns full node details (can be large for big clusters)

get_nodes_summary ✨ NEW

Get a concise summary of nodes organized by datacenter.

• Parameters:
  • cluster_id (required)
  • datacenter (optional) - Filter by specific datacenter
• Returns: Node counts, IPs, hostnames, racks by datacenter
• Use Case: Quick cluster topology overview without large payloads
• Example:

  {
    "total_nodes": 68,
    "datacenter_counts": {
      "us-east1-v1": 15,
      "us-central1-v1": 15,
      "HD_ATC": 18,
      "HD_SSC": 20
    }
  }
  

get_node_info

Get detailed information about a specific node.

• Parameters: cluster_id, node_ip

Metrics Collection

get_cluster_metrics

Retrieve cluster-wide metrics.

• Parameters:
  • cluster_id (required)
  • datacenter (default: "all")
  • metric (required) - e.g., "write-ops", "read-ops", "data-load"
  • start - Unix timestamp in seconds
  • end - Unix timestamp in seconds
  • step - Time interval in minutes (1, 5, 120, or 1440)
  • function - Aggregation: "min", "max", or "average"

Example metrics:

• write-ops: Write requests per second
• read-ops: Read requests per second
• data-load: Live disk space used
• heap-used: Java heap memory usage
• pending-compaction-tasks: Pending compactions

get_node_metrics

Retrieve metrics for a specific node.

• Parameters: Same as cluster metrics, plus node_ip

get_bulk_node_metrics ✨ NEW

Retrieve metrics for ALL nodes in a datacenter with automatic aggregation.

• Parameters:
  • cluster_id (required)
  • datacenter (required) - e.g., "us-east1-v1"
  • metric (required) - e.g., "read-ops", "write-ops"
  • start (optional) - Defaults to 1 hour ago
  • end (optional) - Defaults to current time
  • step (optional) - Default: 5 minutes
  • function (optional) - Default: "average"
• Returns:
  • Aggregate time-series (total, average, min, max per timestamp)
  • Overall statistics
  • Per-node details and error status
• Use Case: Get total read/write volume for entire datacenter
• Example:

  {
    "cluster_id": "Production_Cluster",
    "datacenter": "us-east1-v1",
    "metric": "read-ops",
    "nodes": {"total": 15, "with_data": 15},
    "overall_statistics": {
      "total_sum": 785160,
      "average": 14.54,
      "max": 17.89
    }
  }
  

get_table_metrics

Retrieve metrics for a specific table.

• Parameters:
  • cluster_id, datacenter, keyspace, table, metric
  • Time range and aggregation parameters

Example table metrics:

• cf-write-ops: Table write operations per second
• cf-read-ops: Table read operations per second
• cf-live-disk-used: Disk space used by table
• cf-live-sstables: Number of SSTables

get_new_metrics

Retrieve multiple metrics using the unified API.

• Parameters:
  • cluster_id, metrics (comma-separated)
  • nodes or node_group ("*" for all)
  • step in seconds (60, 300, 7200, or 86400)
  • node_aggregation (0 or 1)

list_available_metrics

List all available metric types with descriptions.

• Parameters: category (optional) - "cluster", "threadpool", "table", "os"

Schema Operations

get_keyspaces

Get list of all keyspaces in a cluster.

• Parameters: cluster_id

get_keyspace_schema

Get schema information for a specific keyspace.

• Parameters: cluster_id, keyspace

Event Monitoring

get_events

Get events and alerts for a cluster.

• Parameters: cluster_id, limit (default: 100)

---

📖 Quick Start Examples

Once configured, you can use the MCP server to monitor your Cassandra clusters:

Example 1: List All Clusters

In VS Code Copilot Chat:

@datastax-opscenter get_cluster_configs

In Claude Desktop:

Show me all Cassandra clusters managed by OpsCenter

Example 2: Get Cluster Topology Overview ✨ NEW

Get a summary of all nodes in "Production_Cluster" organized by datacenter

Using get_nodes_summary tool:

• Shows node counts per datacenter
• Lists node IPs, hostnames, racks
• Lightweight response (no large payloads)

Example 3: Analyze Datacenter Read Volume ✨ NEW

What is the total read request volume for all nodes in us-east1-v1 
datacenter of "Production_Cluster" for the last hour?

Using get_bulk_node_metrics tool:

• Automatically queries all 15 nodes in us-east1-v1
• Aggregates metrics across all nodes
• Returns total, average, min, max statistics
• Includes per-timestamp breakdown

Example 4: Check Cluster Health

Get detailed information about the cluster "Production_Cluster"

Example 5: Monitor Read Performance

Show me read operations per second for "Production_Cluster" 
in the last 3 hours with 5-minute intervals

Example 6: Analyze Table Performance

What is the disk usage and read latency for the table 
"users" in keyspace "app_data" on cluster "Production_Cluster"?

Example 7: Node Health Check

Get heap memory usage and CPU metrics for node 10.0.1.50 
in cluster "Production_Cluster" for the last hour

---

Example 1: Get Cluster Information

// Get all clusters
await callTool("get_cluster_configs", {});

// Get specific cluster details
await callTool("get_cluster_info", {
  cluster_id: "Test_Cluster"
});

Example 2: Monitor Write Performance

// Get write operations per second for last hour
const now = Math.floor(Date.now() / 1000);
const oneHourAgo = now - 3600;

await callTool("get_cluster_metrics", {
  cluster_id: "Test_Cluster",
  datacenter: "all",
  metric: "write-ops",
  start: oneHourAgo,
  end: now,
  step: 5, // 5-minute intervals
  function: "average"
});

Example 3: Check Node Health

// Get node CPU usage
await callTool("get_node_metrics", {
  cluster_id: "Test_Cluster",
  node_ip: "10.11.12.150",
  metric: "os-cpu-user",
  start: oneHourAgo,
  end: now
});

Example 4: Analyze Table Performance

// Get table read latency
await callTool("get_table_metrics", {
  cluster_id: "Test_Cluster",
  datacenter: "all",
  keyspace: "Keyspace1",
  table: "Users",
  metric: "cf-read-latency-op",
  function: "max"
});

Example 5: Discover Available Metrics

// List all cluster metrics
await callTool("list_available_metrics", {
  category: "cluster"
});

// List all available metrics
await callTool("list_available_metrics", {});

Metric Categories

Cluster Metrics

Performance metrics aggregated across the cluster:

• Operations: write-ops, read-ops, write-failures, read-failures
• Latency: write-histogram, read-histogram
• Memory: heap-used, heap-max, nonheap-used
• Cache: key-cache-hit-rate, row-cache-hit-rate
• Compaction: pending-compaction-tasks, total-bytes-compacted

Thread Pool Metrics

Thread pool activity and queue depths:

• Pending: pending-read-stage, pending-mutation-stage, pending-flushes
• Active: active-read-stage, active-mutation-stage
• Completed: completed-read-stage, completed-mutation-stage

Table Metrics

Per-table performance and storage:

• Operations: cf-write-ops, cf-read-ops
• Latency: cf-write-latency-op, cf-read-latency-op
• Storage: cf-live-disk-used, cf-total-disk-used, cf-live-sstables
• SSTable stats: cf-sstables-per-read, cf-partition-size

Operating System Metrics

Host-level resource utilization:

• CPU: os-cpu-user, os-cpu-system, os-cpu-idle, os-load
• Memory: os-memory-used, os-memory-free
• Disk: os-disk-used, os-disk-free, os-disk-read-throughput
• Network: os-net-received, os-net-sent

Time Range Parameters

All metric queries support time range filtering:

• start: Unix timestamp in seconds (beginning of range)
• end: Unix timestamp in seconds (end of range)
• step: Data point interval
  • For legacy API: minutes (1, 5, 120, 1440)
  • For new-metrics API: seconds (60, 300, 7200, 86400)

Aggregation Functions

Metrics can be aggregated using:

• min: Minimum value in the time period
• max: Maximum value in the time period
• average: Average value in the time period

API Reference

Based on DataStax OpsCenter 6.8 API:

• Metrics API Documentation
• OpsCenter API Reference

🛠️ Development

Project Structure

datastax-opscenter-mcp/
├── src/
│   └── index.ts          # Main MCP server implementation
├── build/                # Compiled JavaScript output
│   ├── index.js
│   └── index.d.ts
├── .github/
│   └── copilot-instructions.md  # AI coding assistant guide
├── package.json
├── tsconfig.json
├── .gitignore
└── README.md

Development Commands

# Install dependencies
npm install

# Build the project
npm run build

# Watch mode for development (auto-rebuild on changes)
npm run watch

# Run the compiled server
npm start

# Run directly with environment variables
OPSCENTER_URL=http://localhost:8888 npm start

Making Changes

1. Edit TypeScript source in src/index.ts
2. Run npm run build or npm run watch
3. Restart VS Code or Claude Desktop to pick up changes

Adding New Tools

To add a new MCP tool:

1. Add the tool definition to the tools array in src/index.ts
2. Add the handler case in the CallToolRequestSchema handler
3. Update the README with usage examples
4. Rebuild: npm run build

---

📚 API Reference

Available MCP Tools

🔍 Troubleshooting

Common Issues

❌ "Cannot connect to OpsCenter"

Problem: Error: connect ECONNREFUSED

Solutions:

1. Verify OpsCenter is running:

   curl http://localhost:8888/cluster-configs
   

2. Check the OPSCENTER_URL in your configuration
3. Verify firewall allows connections to OpsCenter port (default: 8888)
4. Test network connectivity:

   telnet your-opscenter-host 8888
   

❌ "Authentication Failed"

Problem: 401 Unauthorized

Solutions:

1. Verify OpsCenter requires authentication (check OpsCenter settings)
2. Set correct OPSCENTER_USERNAME and OPSCENTER_PASSWORD
3. Remove authentication env vars if OpsCenter doesn't require them
4. Check credentials by logging into OpsCenter web UI

❌ "MCP Server Not Showing Up"

VS Code:

1. Check the path in mcp-settings.json is absolute and correct
2. Verify the file exists: ls /path/to/datastax-opscenter-mcp/build/index.js
3. Check for syntax errors in mcp-settings.json
4. Restart VS Code completely
5. Check VS Code Output panel for MCP errors

Claude Desktop:

1. Verify configuration file location matches your OS
2. Use absolute paths in the configuration
3. Quit Claude Desktop completely (not just close window)
4. Check Claude Desktop logs:
   • macOS: ~/Library/Logs/Claude/
   • Windows: %APPDATA%\Claude\logs\

❌ "Metric Not Found"

Problem: API Error (400): Invalid metric

Solutions:

1. Use the list_available_metrics tool to see valid metrics:

   @datastax-opscenter list_available_metrics
   

2. Check metric spelling and hyphens (e.g., read-ops not read_ops)
3. Verify the metric category matches your request:
   • Cluster metrics: use get_cluster_metrics
   • Node metrics: use get_node_metrics
   • Table metrics: use get_table_metrics

❌ "Build Errors"

Problem: TypeScript compilation fails

Solutions:

1. Ensure Node.js version is compatible:

   node --version  # Should be 18.x, 20.x, or 22.x
   

2. Clear and reinstall dependencies:

   rm -rf node_modules package-lock.json
   npm install
   npm run build
   

3. Check TypeScript version:

   npm list typescript
   

🐛 Debug Mode

Enable verbose logging by checking stderr output:

VS Code:

• Check Output panel → Select "MCP" from dropdown

Claude Desktop:

• Check logs directory for your OS (see above)

Manual Testing:

OPSCENTER_URL=http://localhost:8888 node build/index.js

---

🤝 Contributing

Contributions are welcome! Here's how you can help:

Reporting Issues

1. Search existing issues first
2. Include:
   • OpsCenter version
   • Node.js version
   • Error messages and stack traces
   • Steps to reproduce

Submitting Pull Requests

1. Fork the repository
2. Create a feature branch:

   git checkout -b feature/your-feature-name
   

3. Make your changes
4. Test thoroughly:

   npm run build
   # Test with VS Code or Claude Desktop
   

5. Commit with clear messages:

   git commit -m "Add feature: description"
   

6. Push and create a pull request

Development Guidelines

• Follow existing TypeScript code style
• Add JSDoc comments for new functions
• Update README.md with new features
• Test with both authenticated and unauthenticated OpsCenter
• Ensure backwards compatibility

---

📄 License

MIT License - see LICENSE file for details

---

🙏 Acknowledgments

• Model Context Protocol by Anthropic
• DataStax OpsCenter API Documentation
• Apache Cassandra Community

---

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• OpsCenter API Docs: DataStax Documentation

---

🗺️ Roadmap

• [ ] Support for DataStax OpsCenter 7.x
• [ ] Grafana-style dashboard generation
• [ ] Alert configuration tools
• [ ] Backup/restore operations
• [ ] Repair management
• [ ] Performance recommendations
• [ ] WebSocket support for real-time metrics

---

Made with ❤️ for the Cassandra community