Astra DB MCP Server

What is Astra DB MCP Server about?

Provides a Model Context Protocol (MCP) server that allows LLM agents to perform collection‑level operations (create, read, update, delete, bulk actions, search) on an Astra DB instance.

How to use Astra DB MCP Server?

1. Obtain an Astra DB Application Token and the Astra DB API Endpoint from the Astra console.
2. Add the server to an MCP‑compatible client (e.g., Claude Desktop, Cursor) using the JSON snippet below.
3. Set the required environment variables (ASTRA_DB_APPLICATION_TOKEN, ASTRA_DB_API_ENDPOINT) and optionally ASTRA_DB_KEYSPACE.
4. Run the client; the server will launch via npx and connect to the specified Astra DB.

Key Features of Astra DB MCP Server

• Collection management: GetCollections, CreateCollection, UpdateCollection, DeleteCollection
• Record operations: ListRecords, GetRecord, CreateRecord, UpdateRecord, DeleteRecord
• Bulk actions: BulkCreateRecords, BulkUpdateRecords, BulkDeleteRecords
• Search capability: FindRecord, EstimateDocumentCount
• Helper tools: OpenBrowser for auth flow, HelpAddToClient for setup assistance

Use Cases of Astra DB MCP Server

• Enabling autonomous agents to store and retrieve structured data during a conversation.
• Automating ETL pipelines where LLMs generate or modify documents directly in Astra DB.
• Building AI‑powered dashboards that query Astra DB without writing explicit API code.
• Prototyping data‑driven assistants that need real‑time CRUD access to a NoSQL backend.

FAQ from the Astra DB MCP Server

Q: Which environment variables are mandatory? A: ASTRA_DB_APPLICATION_TOKEN and ASTRA_DB_API_ENDPOINT. ASTRA_DB_KEYSPACE is optional.

Q: Can I run the server on Windows? A: Yes. Use cmd with /k to invoke npx as shown in the Claude Desktop instructions.

Q: Do I need to rebuild after changing code? A: No. The eval package loads the MCP client directly; just re‑run the npx command.

Q: How do I add the server to Cursor? A: Either edit the project‑specific .cursor/mcp.json or use the UI wizard, supplying the same command and env variables as for Claude Desktop.

Astra DB MCP Server

A Model Context Protocol (MCP) server for interacting with Astra DB. MCP extends the capabilities of Large Language Models (LLMs) by allowing them to interact with external systems as agents.

Prerequisites

You need to have a running Astra DB database. If you don't have one, you can create a free database here. From there, you can get two things you need:

1. An Astra DB Application Token
2. The Astra DB API Endpoint

To learn how to get these, please read the getting started docs.

Adding to an MCP client

Here's how you can add this server to your MCP client.

Claude Desktop

To add this to Claude Desktop, go to Preferences -> Developer -> Edit Config and add this JSON blob to claude_desktop_config.json:

{
  "mcpServers": {
    "astra-db-mcp": {
      "command": "npx",
      "args": ["-y", "@datastax/astra-db-mcp"],
      "env": {
        "ASTRA_DB_APPLICATION_TOKEN": "your_astra_db_token",
        "ASTRA_DB_API_ENDPOINT": "your_astra_db_endpoint"
      }
    }
  }
}

Optional Keyspace Configuration: By default, this server uses the keyspace configured in the underlying Astra DB library (typically default_keyspace). If you need to connect to a specific keyspace, you can add the ASTRA_DB_KEYSPACE variable to the env object above, like so:

"env": {
  "ASTRA_DB_APPLICATION_TOKEN": "your_astra_db_token",
  "ASTRA_DB_API_ENDPOINT": "your_astra_db_endpoint",
  "ASTRA_DB_KEYSPACE": "your_desired_keyspace"
}

Windows PowerShell Users: npx is a batch command so modify the JSON as follows:

  "command": "cmd",
  "args": ["/k", "npx", "-y", "@datastax/astra-db-mcp"],

Cursor

To add this to Cursor, go to Settings -> Cursor Settings -> MCP

From there, you can add the server by clicking the "+ Add New MCP Server" button, where you should be brought to an mcp.json file.

Tip: there is a ~/.cursor/mcp.json that represents your Global MCP settings, and a project-specific .cursor/mcp.json file that is specific to the project. You probably want to install this MCP server into the project-specific file.

Add the same JSON as indiciated in the Claude Desktop instructions.

Alternatively you may be presented with a wizard, where you can enter the following values (for Unix-based systems):

• Name: Whatever you want
• Type: Command
• Command:

env ASTRA_DB_APPLICATION_TOKEN=your_astra_db_token ASTRA_DB_API_ENDPOINT=your_astra_db_endpoint npx -y @datastax/astra-db-mcp

Note: ASTRA_DB_KEYSPACE is optional. If omitted, the default keyspace configured in the Astra DB library will be used.

Once added, your editor will be fully connected to your Astra DB database.

Available Tools

The server provides the following tools for interacting with Astra DB:

• GetCollections: Get all collections in the database
• CreateCollection: Create a new collection in the database
• UpdateCollection: Update an existing collection in the database
• DeleteCollection: Delete a collection from the database
• ListRecords: List records from a collection in the database
• GetRecord: Get a specific record from a collection by ID
• CreateRecord: Create a new record in a collection
• UpdateRecord: Update an existing record in a collection
• DeleteRecord: Delete a record from a collection
• FindRecord: Find records in a collection by field value
• BulkCreateRecords: Create multiple records in a collection at once
• BulkUpdateRecords: Update multiple records in a collection at once
• BulkDeleteRecords: Delete multiple records from a collection at once
• OpenBrowser: Open a web browser for authentication and setup
• HelpAddToClient: Get assistance with adding Astra DB client to your MCP client
• EstimateDocumentCount: Get estimate of the number of documents in a collection

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Running evals

The evals package loads an mcp client that then runs the index.ts file, so there is no need to rebuild between tests. You can load environment variables by prefixing the npx command. Full documentation can be found here.

OPENAI_API_KEY=your-key  npx mcp-eval evals.ts tools.ts

❤️ Contributors

Badges