Astra Datastax MCP (Data API Edition)

A Model Context Protocol (MCP) server for connecting Claude AI to Astra Datastax Serverless databases using the Data API.

Note: This version uses the Data API exclusively, connecting via Application Token and API Endpoint. It does not use the Secure Connect Bundle or CQL driver.

Features

• Connect to Astra Datastax using Application Token and API Endpoint provided via a JSON config file.
• Manage collections (create, list, get info).
• Perform document operations (insert, find, update, delete).
• Execute vector similarity searches on vector-enabled collections.

Prerequisites

• Node.js (v14 or later)
• An Astra Datastax account with a database (https://astra.datastax.com/)
• An Application Token (ASTRA_DB_APPLICATION_TOKEN starting with AstraCS:...)
• Your database API Endpoint (ASTRA_DB_API_ENDPOINT like https://<db_id>-<region>.apps.astra.datastax.com)
• A JSON configuration file containing your token and endpoint.

Installation

Using npx (Recommended)

No installation needed! You can run directly with npx:

# Ensure you have the latest version if you ran it before
npx astra-datastax-mcp@latest

Global Installation

# Ensure you have the latest version
npm uninstall -g astra-datastax-mcp
npm install -g astra-datastax-mcp@latest

Then you can run it with:

astra-datastax-mcp

Configuration

1. Create a JSON Configuration File: Create a file (e.g., astra_config.json) somewhere accessible to the MCP server process. Add your credentials like this:

   {
     "ASTRA_DB_APPLICATION_TOKEN": "AstraCS:YourTokenValue...",
     "ASTRA_DB_API_ENDPOINT": "https://your-db-id-region.apps.astra.datastax.com"
   }

   SECURITY: Protect this file appropriately, as it contains sensitive credentials.

2. Configure Claude Desktop: Add the server configuration to claude_desktop_config.json (location depends on your OS - see old README section if needed). Crucially, ensure the command can execute the MCP server. Using npx is often simplest:

   {
     "mcpServers": {
       "astra-datastax": {
         "command": "npx astra-datastax-mcp@latest"
       }
     }
   }

Usage with Claude

1. Connect: Start by asking Claude to connect using your config file: "Connect to my Astra DB using the astra-datastax MCP server. My configuration file is at /path/to/your/astra_config.json."

2. Interact: Once connected, you can use the available tools:

   • "List all collections in my Astra database using astra-datastax."
   • "Create a new collection named 'my_vectors' with options { vector: { dimension: 768, metric: \"cosine\" } } using astra-datastax."
   • "Insert these documents into the 'users' collection: [{ \"name\": \"Alice\", \"email\": \"[email protected]\" }, { \"name\": \"Bob\" }] using astra-datastax."
   • "Find documents in the 'products' collection where the filter is { \"category\": \"electronics\" } using astra-datastax."
   • "Find similar documents in 'my_vectors' using the vector [0.1, 0.2, ..., 0.9] and options { limit: 3 } using astra-datastax."
   • "Delete documents from the 'logs' collection where the filter is { \"level\": \"debug\" } using astra-datastax."
   • "Get information about the 'orders' collection using astra-datastax."
   • "Disconnect from Astra DB using astra-datastax."

Available Tools

• connect_data_api(config_json_path): Connects using credentials from a JSON file.
• disconnect_data_api(): Disconnects the current session.
• list_collections(): Lists all collections.
• get_collection_info(collection_name): Checks if a collection exists and returns basic info.
• create_collection(collection_name, options): Creates a collection (optionally vector-enabled).
• insert_documents(collection_name, documents): Inserts an array of documents.
• find_documents(collection_name, filter, options): Finds documents using filters and options (limit, projection).
• find_vector_documents(collection_name, vector, options): Performs vector similarity search.
• update_documents(collection_name, filter, update): Updates documents matching a filter.
• delete_documents(collection_name, filter): Deletes documents matching a filter.

Debugging

The server creates a debug log at /tmp/astra-mcp-debug.log (location might vary based on OS temp directory).

Security Notes

• Configuration File Security: The JSON configuration file contains your sensitive Application Token. Ensure it has appropriate file permissions and is not exposed unintentionally.
• File Access: The connect_data_api function reads a file path provided during the conversation. The MCP server process needs read access to this path. Run the server with appropriate permissions and be mindful of the paths you provide.
• The server does not permanently store credentials read from the file; they are kept in memory only for the session duration.

License

MIT