Provides tools for interacting with DataStax Astra DB, including database overview, collection and table schema exploration, vector and hybrid search, document CRUD, and database administration with guarded writes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@astra-mcp What's in my Astra database?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
npx -y @erichare/astra-mcp initinit 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:
Paste an application token at a hidden prompt. Create one in the Astra console under Settings → Tokens.
Pick a database and a keyspace.
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.jsoninto 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.
Related MCP server: MCP Database Manager
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.
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 | |
Connect |
|
Explore |
|
Query |
|
Build |
|
Change |
|
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.
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.
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.
Agent | What you get | Manual setup |
Claude Code | Plugin: skills, |
|
OpenAI Codex | Plugin: skills ( |
|
Cursor | MCP server in | |
VS Code (Copilot) | MCP server in your user profile | |
Windsurf | MCP server in |
|
Gemini CLI | MCP server in |
|
Claude Desktop | MCP server in | Or open |
IBM Bob | Skills, | |
ChatGPT, claude.ai | Hosted server with OAuth | |
Any MCP client | stdio server |
|
Skills-only harnesses that read the Agent Skills layout can take the skills/ directory as is.
Skill | Purpose |
| The 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 |
| When to show a view, and how to render one where MCP Apps aren't available |
| Connect a project, and diagnose one that isn't working, with the exact fix per failure |
| Review the project's data model and Data API usage against the live schema |
| Shortcuts you invoke; the agent doesn't trigger them on its own |
| Personas: a read-only code reviewer in a forked context, a schema designer, and a staged migration planner |
Each value (token, endpoint, keyspace) comes from the first place that has it:
The server's environment: ASTRA_DB_APPLICATION_TOKEN, ASTRA_DB_API_ENDPOINT, ASTRA_DB_KEYSPACE
The project's .env.local or .env, searched upward to the git root
The host's settings (the Claude Code plugin or the Claude Desktop bundle)
Your profile, written by login --global
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.
Tools · Configuration · Security · Hosted server · IBM Bob · Troubleshooting · Privacy · Publishing · Changelog
cd server && npm ci && npm test # server, CLI, hosted, and UI view tests
node --test tests/*.test.mjs # hooks, manifests, skills, scriptsSee CONTRIBUTING.md for the layout and checks, and AGENTS.md if you're a coding agent working on this repository.
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.
This server cannot be deployed
Store, query, and update structured data from any AI agent
The all-in-one data stack for agents. Upload files, run SQL, evolve tables, and render charts.
Gateway between LLM agents and world data through eight tools and a bundled endpoint catalog.
Database for your AI agent. Turn its output into data, docs, skills, and apps you can actually use.
