Back to Directory/Databases

Astra DB

Astra DB tools for agents: schema, find, vector search, guarded writes, and interactive views.

DatabasesTypeScriptv2.0.0
View on GitHub

Give your coding agent a live view of your Astra DB. It can map a database, read a collection's real schema before writing code against it, run vector and hybrid searches, page through documents, and change data, asking you first before anything destructive. When it writes application code, it starts from canonical Data API snippets for Python, TypeScript, Java, C#, and Go instead of guessing.

Quickstart

npx -y @erichare/astra-mcp init

init finds the agents on your machine and sets each one up. Claude Code and Codex get the full plugin (skills, hooks, and the MCP server) from their plugin marketplaces; the others get the MCP server in their config. Then it connects a database:

  1. Paste an application token at a hidden prompt. Create one in the Astra console under Settings → Tokens.
  2. Pick a database and a keyspace.
  3. ASTRA_DB_APPLICATION_TOKEN, ASTRA_DB_API_ENDPOINT, and ASTRA_DB_KEYSPACE are written to ./.env (mode 0600), and login offers to add .env to .gitignore if it isn't ignored yet.

No restart needed: the server re-reads credentials on every call. Now ask your agent:

What's in my Astra database?

Find articles similar to "how do black holes evaporate".

Write a TypeScript script that loads products.json into a new vectorize collection.

Needs Node.js 20+. Prefer a one-liner? curl -fsSL https://raw.githubusercontent.com/erichare/astra-db-plugin/main/install.sh | sh (PowerShell: irm https://raw.githubusercontent.com/erichare/astra-db-plugin/main/install.ps1 | iex) runs the same init.

See your data

In hosts that render MCP Apps, such as Claude and ChatGPT, the overview, schema, explorer, and search tools answer with an interactive view: drill from a database into a collection, its documents, and similar documents, with a Back history, your host's theme, and full keyboard support. Elsewhere, the agent gets the same data as text, and can write a standalone HTML page when you ask for a visual.

Vector search results: ranked hits with similarity bars and score statistics Collection view: vector and vectorize settings, lexical and rerank, sample document
Database overview: keyspaces, collections with vector settings and counts, tables Explorer: documents table with field inventory, filters, and paging
Table view: columns, primary key, indexes, vector columns Similarity map: hits placed by score around the query

In Claude Code, the shortcuts are /astra-db:overview, /astra-db:collection <name>, /astra-db:explore <name> [--filter '<json>'], and /astra-db:similar "<query>" <collection>.

Tools

Tools
Connectconnection_status shows where each credential comes from and runs a live check; list_databases
Exploredatabase_overview, describe_collection, describe_table, list_vectorize_providers
Queryfind (filter, sort, projection, paging), vector_search (text via vectorize, a vector, or "more like this document"; hybrid with rerank), count, distinct_values
Buildcode_examples searches the bundled, documentation-derived client snippets, offline
Changeinsert, update, delete, create_collection, create_table, create_index, drop

Every data tool takes an optional database (name, id, or endpoint) and keyspace, so one server covers all your databases. The server also exposes astra://databases and per-collection schema resources, plus overview, explore, similar, and setup prompts. Arguments, outputs, and error codes: docs/tools.md.

Safe by default

  • Destructive changes need your say-so. drop, and update or delete across many documents or with an empty filter, need confirmation. Clients that support elicitation ask you directly. Otherwise the agent has to show you what will be lost and wait for your approval; the request that started it doesn't count.
  • Read-only when you want it. ASTRA_MCP_READ_ONLY=1, astra-mcp serve --read-only, or the plugin's Read-only setting removes every write tool.
  • Tokens stay out of the chat. login reads the token with hidden input, and the tools send the agent to login, never to you for a token. If you paste one anyway, the agent is told not to use it and to suggest rotating it.
  • A guard against leaks. In Claude Code, Codex, and Bob, a hook stops AstraCS: tokens from being written anywhere except a git-ignored .env. Removing a leaked token is always allowed.
  • Hosted writes are opt-in, per connection: the Allow writes box on the OAuth consent page, or an explicit header.

More in docs/security.md.

Works with

init handles all of these; pick a subset with --agents claude-code,cursor, use project-level files with --project, and preview with --dry-run. npx -y @erichare/astra-mcp uninstall reverses it.

AgentWhat you getManual setup
Claude CodePlugin: skills, /astra-db:* shortcuts, hooks, MCP server, settings for token, endpoint, keyspace, and read-onlyclaude plugin marketplace add erichare/astra-db-plugin
claude plugin install astra-db@astra-db-marketplace
OpenAI CodexPlugin: skills ($astra-db:*), hooks, MCP servercodex plugin marketplace add erichare/astra-db-plugin
codex plugin add astra-db@astra-db-marketplace
CursorMCP server in ~/.cursor/mcp.jsonAdd to Cursor
VS Code (Copilot)MCP server in your user profileInstall in VS Code
WindsurfMCP server in ~/.codeium/windsurf/mcp_config.jsoninit --agents windsurf
Gemini CLIMCP server in ~/.gemini/settings.jsoninit --agents gemini
Claude DesktopMCP server in claude_desktop_config.jsonOr open astra-db.mcpb for a one-click install with a settings form
IBM BobSkills, /astra-* commands, three custom modes, rules, hooks, MCP server in ~/.bob/docs/bob.md
ChatGPT, claude.aiHosted server with OAuthdocs/hosted.md
Any MCP clientstdio servernpx -y @erichare/astra-mcp

Skills-only harnesses that read the Agent Skills layout can take the skills/ directory as is.

What the agent knows

SkillPurpose
astra-toolkitThe knowledge base: Collections vs Tables, data modeling, the Astra CLI, application architecture, and about 340 examples per language with per-language indexes. Written by Stefano Lottini (IBM / DataStax), vendored and extended here
astra-widgetsWhen to show a view, and how to render one where MCP Apps aren't available
setup, doctorConnect a project, and diagnose one that isn't working, with the exact fix per failure
data-model-reviewReview the project's data model and Data API usage against the live schema
overview, collection, explore, similarShortcuts you invoke; the agent doesn't trigger them on its own
reviewer, data-modeler, migration-helperPersonas: a read-only code reviewer in a forked context, a schema designer, and a staged migration planner

Configuration

Each value (token, endpoint, keyspace) comes from the first place that has it:

  1. The server's environment: ASTRA_DB_APPLICATION_TOKEN, ASTRA_DB_API_ENDPOINT, ASTRA_DB_KEYSPACE
  2. The project's .env.local or .env, searched upward to the git root
  3. The host's settings (the Claude Code plugin or the Claude Desktop bundle)
  4. Your profile, written by login --global
  5. The Astra CLI's ~/.astrarc (token only)

With a token but no endpoint, the server picks your only active database, or the one named by ASTRA_DB_NAME. npx -y @erichare/astra-mcp doctor shows what it found and where. Full reference: docs/configuration.md.

Documentation

Tools · Configuration · Security · Hosted server · IBM Bob · Troubleshooting · Privacy · Publishing · Changelog

Contributing

cd server && npm ci && npm test      # server, CLI, hosted, and UI view tests
node --test tests/*.test.mjs         # hooks, manifests, skills, scripts

See CONTRIBUTING.md for the layout and checks, and AGENTS.md if you're a coding agent working on this repository.

License and provenance

The plugin, server, installer, hooks, and assets are Apache-2.0. The astra-toolkit skill content is vendored from sl-at-ibm/astra-toolkit-skill and derives from the DataStax documentation; the changes made here are listed in NOTICE. This is a community project, not an official DataStax, IBM, Anthropic, or OpenAI product. Product names and logos identify compatibility only and are trademarks of their owners.

Installation

Source-derived launch command. Check the maintainer’s required arguments and credentials before running:

bash
npx -y @erichare/astra-mcp

Set up in your AI client

Merge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.

json
{
  "mcpServers": {
    "io-github-erichare-astra-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@erichare/astra-mcp"
      ]
    }
  }
}

Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.

Claude Desktop setup reference

Package

@erichare/astra-mcpnpm

Compatible MCP Clients

Astra DB works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.

  • Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.
  • Cursor~/.cursor/mcp.jsonRestart Cursor for changes to take effect.
  • VS Code.vscode/mcp.jsonReload VS Code window for changes to take effect.
  • Windsurf~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect.
  • Claude Code.mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.

Learn More

BigQuery MCP Server: Set Up the Prebuilt ToolboxA complete configuration path for BigQuery Toolbox: project prerequisites, credentials, binary selection, prebuilt arguments, and a read-first connection check.Read articleSQLite MCP Server: Query a Local Database From ClaudeSQLite is the simplest database to hand an AI agent, since the whole thing lives in one file. This guide walks through picking a SQLite MCP server from the directory, configuring it in Claude Desktop, and the permission tradeoffs worth knowing before you let an agent write to your data.Read articleMongoDB MCP vs Redis MCP: Which Fits Agent Memory?MongoDB and Redis both ship official MCP servers, but they solve different problems for AI agents. Here's a data-backed comparison of auth models, tool coverage, and which one fits agent memory versus persistent storage.Read article