AWS Keyspaces MCP Server

What is AWS Keyspaces MCP Server?

The AWS Keyspaces MCP Server is a lightweight, open-source component in the AWS MCP Servers suite that enables LLM-powered tools and agents to seamlessly interact with Amazon Keyspaces (for Apache Cassandra) databases. Implementing the Model Context Protocol (MCP), it exposes secure endpoints to discover keyspaces and tables, execute Cassandra Query Language (CQL) SELECT queries, and analyze schema designs—making it easy for AI assistants to deliver cloud-aware insights, automate Cassandra operations, and support code or workflow generation.

How to Configure AWS Keyspaces MCP Server

Prerequisites:
- Install uv for Python virtual environments.
- Set up Python 3.10 or later via uv python install 3.10.
- Ensure your AWS credentials grant access to required Amazon Keyspaces resources and regions.
Add Server to MCP Client Configuration:
- In your MCP client config file (e.g., ~/.aws/amazonq/mcp.json, .cursor/mcp.json, or WindSurf config), insert the following entry:
```
"awslabs.amazon-keyspaces-mcp-server": {
  "command": "uvx",
  "args": ["awslabs.amazon-keyspaces-mcp-server@latest"],
  "env": {
    "AWS_PROFILE": "your-aws-profile",
    "AWS_REGION": "us-east-1",
    "FASTMCP_LOG_LEVEL": "ERROR"
  }
}
```
- Replace "your-aws-profile" and "us-east-1" with your actual AWS profile and region.
- Optionally, add IAM roles or custom environment variables for enhanced security or access control.
Container Option:
- Build and run the MCP server as a Docker container if desired, configuring environment variables with --env or --env-file and mounting your AWS credentials directory if using profiles.
Validate Installation:
- Ensure the server appears as enabled in your client tool's MCP server list and is reachable for tool discovery and invocation.

How to Use AWS Keyspaces MCP Server

Enable Server in Your AI Tool
- Use your IDE extension, chat interface, or MCP-compatible LLM client to enable the AWS Keyspaces MCP Server.
- Ensure your session uses the preset AWS credentials and region.
Discover Tools
- Use the tools/list endpoint or your agent's GUI to view available AWS Keyspaces operations such as keyspace/table exploration and query execution.
Execute Operations
- Via natural language or structured requests, instruct your AI assistant to:
  - List available keyspaces or tables
  - Retrieve keyspace/table schemas
  - Execute CQL SELECT queries to fetch data or analyze usage
  - Request schema analysis or optimization suggestions
Review and Approve Actions
- Depending on your MCP client settings, manually approve actions like CQL query execution or schema analysis, or enable auto-approve for faster workflows.
Integrate in Workflows
- Use AWS Keyspaces MCP Server as part of larger AI-driven automations—e.g., generate IaC code based on your DB structure, validate schema designs, or fetch live data insights within your cloud projects.

Key Features

Keyspace & Table Discovery: Enumerate all Amazon Keyspaces and tables within your AWS account and specified region.
CQL Query Execution: Run CQL SELECT queries directly from your LLM assistant, with secure credential handling and limits on supported query types.
Schema Introspection: Retrieve complete schemas for keyspaces and tables, including columns, types, and table properties.
Schema Analysis & Guidance: Analyze table design, data modeling, and query performance with best-practice insights for Apache Cassandra.
Cassandra-Compatible: Fully supports Cassandra Query Language (CQL) operations compatible with Amazon Keyspaces.
Secure Access: Uses AWS IAM roles/profiles or specified credentials; applies MCP best practices for data protection.
Flexible Integration: Usable from IDEs, chatbots, and any agentic MCP client for interactive or automated workflows.

Use Cases

Cloud Data Exploration: Instantly explore and visualize Keyspaces schemas and sample data without manual console navigation.
AI-Assisted Troubleshooting: Instruct your AI assistant to fetch diagnostics or run specific CQL queries to support debugging.
Schema Optimization: Analyze table designs for performance, denormalization, or partition key selection with automated recommendations.
Automated Code Generation: Use live table schema data to generate backend code, ORM mappings, or migration scripts.
DevOps and DataOps Workflows: Integrate Keyspaces data access into larger infrastructure-as-code, migration, or observability pipelines powered by LLMs.
Natural Language to CQL: Empower business users or junior developers to retrieve Keyspaces data simply by asking questions in plain English.

FAQ

Q1: Does the MCP Server support writes (INSERT/UPDATE/DELETE) to Keyspaces, or only SELECT queries?
A1: The AWS Keyspaces MCP Server currently focuses on read-only operations, such as executing CQL SELECT queries and exploring schemas, to ensure security and avoid unintended data modifications. Future releases may consider write support with robust safeguards.

Q2: How is access to my Keyspaces data secured when using the MCP Server?
A2: All operations use your configured AWS credentials/roles, and the MCP Server follows best practices for credential management and secure IAM scoping. Data is never exposed to external networks except via your explicit, authenticated requests.

Q3: What happens if my CQL query is too complex or unsupported?
A3: The server validates and sanitizes incoming queries, supporting only SELECT statements. Complex or unsupported queries will result in a descriptive error, ensuring no unsafe or untested operations are run on your Keyspaces cluster.

Q4: Can the MCP Server be used with multiple regions or AWS accounts at once?
A4: You can run separate instances of the AWS Keyspaces MCP Server with different AWS profiles or region settings to access multiple Keyspaces environments in parallel. Each instance is isolated by its configured credentials.

Q5: Is it possible to use this server as part of a larger agentic workflow involving other AWS services?
A5: Yes, the AWS Keyspaces MCP Server is designed to slot into complex, multi-server AI workflows, and it can operate alongside other AWS MCP Servers to provide comprehensive cloud development and management capability.

Tool Name	Description
list_keyspaces	Returns a list of all available Amazon Keyspaces (Cassandra) keyspaces accessible via the configured AWS credentials and region. Enables discovery and selection for further schema or data exploration.
list_tables	Lists all tables within a specified keyspace. Allows AI assistants and users to enumerate data structures for exploration, documentation, or code generation.
get_table_schema	Retrieves detailed schema information for a specified table, including columns, types, partition keys, and clustering columns. Supports schema introspection, reverse engineering, and design validation.
execute_cql_select	Executes a validated CQL SELECT query against the specified keyspace and table, returning result rows. Enables natural language or structured data retrieval, BI use, and troubleshooting within Keyspaces.
analyze_schema_design	Provides automated analysis and recommendations for a given table schema or query, including best practices for performance, scaling, and partitioning in Amazon Keyspaces (Cassandra).