Provides AI clients with schema-first access to a graph-traversable database for persistent, semantically searchable memory.
Also known as rush-db/mcp-server, @rushdb/mcp-server
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- Apache-2.0
What is RushDB MCP?
RushDB provides AI clients with schema-first access to a graph-traversable database for persistent, semantically searchable memory.
Summary generated from the project's README
About RushDB MCP server
Providing AI agents with persistent, structured memory is what mcp-server enables through its connection to RushDB. Developers can equip clients like Claude Desktop, Cursor, Windsurf, and ChatGPT with a graph-traversable database that supports semantic search without requiring manual management of embeddings or schemas. The server offers two primary connection methods: a remote OAuth flow for web-based clients like Claude.ai and ChatGPT, or a local stdio setup using an API key for desktop and IDE-based tools.
Users can interact with the database using over 40 specialized tools for record management, relationship traversal, and advanced searching. The system supports keyword search via BM25 text indexes, vector similarity through vectorSearch, and complex graph queries. While the Cloud version includes natural-language smartSearch and automated relationship pattern analysis, the local standalone engine provides a direct way to run the Rust engine for development. This setup allows agents to discover schemas, create records, and navigate connected data points to maintain long-term context.
What you can do with it
- 1Storing structured session decisionsAn agent can record specific project decisions to ensure they are remembered in future conversations.
- 2Navigating complex data relationshipsDevelopers can ask an AI to find all information connected to a specific system component by traversing the graph.
- 3Performing semantic and keyword searchesAn AI client can locate specific information using either natural language similarity or exact keyword matching.
- 4Automated schema discoveryAn agent can automatically learn the structure of the database to write accurate queries.
Written from the project's README. Every use case is checked against a quote from it.
How to install RushDB MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall RushDB MCP in Claude Code
$ claude mcp add mcp-server -- npx -y @rushdb/mcp-serverInstall RushDB MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@rushdb/mcp-server"
]
}
}
}Install RushDB MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@rushdb/mcp-server"
]
}
}
}Install RushDB MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-server","type":"stdio","command":"npx","args":["-y","@rushdb/mcp-server"]}'Install RushDB MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@rushdb/mcp-server"
]
}
}
}Install RushDB MCP in Codex
$ codex mcp add mcp-server -- npx -y @rushdb/mcp-serverInstall RushDB MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-server] command = "npx" args = ["-y", "@rushdb/mcp-server"]
Install RushDB MCP in Gemini CLI
$ gemini mcp add -s user mcp-server npx -- -y @rushdb/mcp-serverInstall RushDB MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@rushdb/mcp-server"
]
}
}
}Configuration
RUSHDB_API_KEYRUSHDB_ENGINE_TOKENRUSHDB_ENGINE_URLRUSHDB_MODERUSHDB_TOKEN
| Name | Description | |
|---|---|---|
| RUSHDB_API_KEY | — | |
| RUSHDB_ENGINE_TOKEN | — | |
| RUSHDB_ENGINE_URL | — | |
| RUSHDB_MODE | — | |
| RUSHDB_TOKEN | — |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablerush-db/mcp-server is public and reachablegithub.com/rush-db/mcp-server ↗Pass
- Package names this repository as its source@rushdb/mcp-server names rush-db/mcp-server as sourcenpmjs.com/package/@rushdb/mcp-server ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @rushdb/mcp-servernpmjs.com/package/@rushdb/mcp-server/v/3.4.1#provenance ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/rush-db/mcp-server ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @rushdb/mcp-serverPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubRushDB MCP Server
Connect MCP clients to RushDB, the database for AI.
Connect RushDB to any MCP-compatible AI client and your agent gains persistent, structured memory — semantically searchable and graph-traversable, without managing embeddings or schemas.
Works with ChatGPT, Claude.ai, Claude Desktop, Cursor, Windsurf, Gemini CLI, and any MCP-compatible tool.
Two ways to connect
Remote OAuth (no installation)
For ChatGPT, Claude.ai, and other web-based AI clients — connect directly without installing anything locally:
MCP endpoint: https://mcp.rushdb.com/mcp
Your client redirects to RushDB for OAuth sign-in and receives a scoped token. No API key setup required.
ChatGPT:
- Go to Settings → Connectors → Add connector
- Enter
https://mcp.rushdb.com/mcp - Sign in with your RushDB account
Claude.ai:
- Go to Settings → Integrations → Add integration
- Enter
https://mcp.rushdb.com/mcp - Authorize with your RushDB account
Local (RushDB Cloud API key)
For Claude Desktop, Cursor, Windsurf, VS Code, and other stdio MCP clients:
1. Get an API key at app.rushdb.com
2. Add to your MCP client config:
{
"mcpServers": {
"rushdb": {
"command": "npx",
"args": ["@rushdb/mcp-server"],
"env": {
"RUSHDB_API_KEY": "your-api-key-here"
}
}
}
}
Place this in:
- Claude Desktop —
~/Library/Application Support/Claude/claude_desktop_config.json - Cursor — MCP settings in the Cursor config panel
- Windsurf —
~/.codeium/windsurf/mcp_config.json
3. That's it. The agent now has 43 tools for storing, querying, searching and traversing structured memory.
RUSHDB_API_URLis optional and defaults tohttps://api.rushdb.com/api/v1, the RushDB Cloud API.
Local standalone engine (no Cloud account)
Run the Rust engine, then point a local stdio MCP client at it. This mode calls the public engine protocol directly; it does not use a RushDB Cloud API key, dashboard, or OAuth.
RUSHDB_TOKEN=local-development-token rushdb up --data-dir ./rushdb-data
{
"mcpServers": {
"rushdb": {
"command": "npx",
"args": ["-y", "@rushdb/mcp-server"],
"env": {
"RUSHDB_MODE": "direct",
"RUSHDB_ENGINE_URL": "http://127.0.0.1:3000",
"RUSHDB_ENGINE_TOKEN": "local-development-token"
}
}
}
}
Direct mode offers every tool whose work the engine does: schema discovery, record reads and writes (with
ordering, projections and aggregations), relationships, labels and properties, bulk import and CSV export, text
indexes and keyword search, and external vector indexes with vector search by a queryVector you supply.
The RushDB Cloud tools are not listed and are refused if called: smartSearch (natural-language search),
the relationship-pattern tools, and anything that needs managed embeddings (a text query for vector search,
managed indexes). The MCP HTTP transport is unavailable in direct mode because its OAuth flow belongs to
RushDB Cloud; run the server through stdio on the same machine as the client.
Compatibility
| Package | RushDB 3.x and RushDB Cloud | RushDB 2.x (legacy) |
|---|---|---|
@rushdb/javascript-sdk |
3.x | 2.11.0: npm i @rushdb/javascript-sdk@2 |
rushdb (PyPI) |
3.x | 2.10.0: pip install "rushdb<3" |
@rushdb/mcp-server |
3.x | 2.13.0: npx @rushdb/mcp-server@2 |
What an agent can do
After connecting, ask Claude or your agent naturally:
"Remember that we decided to use Clerk for auth, replacing Auth0, on 2026-04-10."
The agent calls createRecord to store a structured memory. Later:
"What auth decisions have we made?"
The agent calls getSchemaMarkdown to learn what is stored, then findRecords, textSearch or vectorSearch.
"Show me everything related to our auth system."
The agent calls findRelationships and findRecords with relationship filters to traverse the graph of connected records.
Available tools
52 tools, named exactly as below. In direct mode the twelve RushDB Cloud tools are not listed. The full reference, with inputs and safety levels, is at docs.rushdb.com/3.x/learn/reference/mcp/tools.
Discovery and properties
| Tool | What it does |
|---|---|
getSchemaMarkdown |
The whole graph schema as compact Markdown; call once at session start |
getSchema |
Structured schema JSON, with property IDs and vector indexes |
findLabels |
List or filter record labels and their counts |
findProperties |
Property names, types, IDs and record counts |
findPropertyById |
Metadata for one property |
propertyValues |
Numeric or date ranges, or distinct values; with query, the matching values and their counts (match: similar for near spellings; domainOnMiss lists a small field's values when nothing matches) |
searchValues |
Where a value from the question is stored: matches across every property, with label, property and record count |
getSchemaSummary |
Every label's properties with distinct counts, ranges and the values of small fields, in one live read |
resolveNames |
The real label or property behind a name that is not in the schema (patients → Patient) |
getJoinCandidates |
How labels reference each other, from property names and exact value containment, with evidence (RushDB Cloud only) |
deleteProperty |
Remove a property and its values from all records |
getSearchQuerySpec |
The complete SearchQuery syntax reference |
getQueryBuilderPrompt |
The built-in query builder prompt (for clients without MCP Prompts support) |
Records
| Tool | What it does |
|---|---|
findRecords |
Search records; ordering, projections, grouping and aggregations |
findOneRecord |
The first matching record |
findUniqRecord |
Exactly one matching record; fails on zero or several |
getRecord |
One record by ID |
getRecordsByIds |
Several records by ID |
createRecord |
Insert or upsert one record |
updateRecord |
Update some fields of a record |
setRecord |
Replace all fields of a record |
deleteRecord / deleteRecordById |
Delete one record by ID |
bulkCreateRecords |
Insert or upsert many records with one label |
bulkDeleteRecords |
Delete the records matching a query |
exportRecords |
Export matching records as CSV |
Relationships
| Tool | What it does |
|---|---|
findRelationships |
Find relationships by type, properties or endpoint records |
attachRelation |
Create relationships between existing records |
updateRelation |
Change or remove properties on existing relationships; types stores an ISO string as a datetime (RushDB 3.0.4+) |
detachRelation |
Remove relationships: every type unless relationType is given, both ways unless direction is |
Vector, keyword and hybrid search
| Tool | What it does |
|---|---|
findEmbeddingIndexes |
List embedding indexes and their status |
createEmbeddingIndex |
Create an embedding index (on a self-hosted engine, an external one with dimensions) |
getEmbeddingIndexStats |
How many records an index covers and has vectors for |
upsertEmbeddingVectors |
Write your own vectors to an external index |
deleteEmbeddingIndex |
Delete an embedding index and its vectors |
vectorSearch |
Rank records by vector similarity after exact filtering; add text for hybrid search |
semanticSearch |
Deprecated alias for vectorSearch |
listTextIndexes |
List text indexes and their status |
createTextIndex |
Declare a BM25 text index over one property, or * for every string |
deleteTextIndex |
Drop a text index |
textSearch |
Keyword (BM25) search after exact filtering |
RushDB Cloud only
| Tool | What it does |
|---|---|
smartSearch |
Turn a natural-language request into SQL and run it |
listRelationshipPatterns |
List inferred relationship patterns and analysis status |
analyzeRelationshipPatterns |
Queue schema analysis for relationship suggestions |
approveRelationshipPattern |
Approve and apply a suggested pattern |
ignoreRelationshipPattern |
Ignore a suggested pattern |
deleteRelationshipPattern |
Delete a pattern and optionally its materialized relationships |
Connections and imports (RushDB Cloud only)
Data synced from SaaS tools (CRM, billing, support, issue tracking, docs, spreadsheets) and background file imports. The agent checks freshness before answering about recent data and offers a sync rather than starting one unasked.
| Tool | What it does |
|---|---|
listConnections |
The project's connections: status, schedule, last success and error, per-stream label, record count and last sync |
getConnection |
One connection by id (credentials are never returned) |
syncConnection |
Start a sync now, of every enabled stream or the ones named (full re-reads everything); returns the run. Writes |
listImports |
Import runs (file imports and connection syncs), filterable by kind and connectionId |
getImport |
One run's status, per-file or per-stream progress, error sample and summary |
Utilities
| Tool | What it does |
|---|---|
helpAddToClient |
Setup instructions for your MCP client |
Writes accept an optional transactionId.
Built-in query builder prompt
RushDB exposes a system prompt via the MCP Prompts API that teaches the agent to query safely — discover labels and properties first, then construct queries.
How it works:
- Client calls
prompts/list→ findsrushdb.queryBuilder - Client calls
prompts/get→ injects it as the session system message - Agent now does discovery-first queries automatically
Most MCP clients handle this at session start. If your client doesn't support MCP Prompts, call getQueryBuilderPrompt and inject the result as your system message.
Environment variables
These apply to local (API key) mode. Remote OAuth connections do not use environment variables.
| Variable | Required | Description |
|---|---|---|
RUSHDB_API_KEY |
yes | Your RushDB API key |
RUSHDB_API_URL |
no | API base URL (default: https://api.rushdb.com/api/v1) |
For standalone direct mode, use these instead:
| Variable | Required | Description |
|---|---|---|
RUSHDB_MODE |
yes | Set to direct. |
RUSHDB_ENGINE_URL |
yes | Standalone engine base URL, for example http://127.0.0.1:3000. |
RUSHDB_ENGINE_TOKEN |
yes | Token configured for the standalone engine. |
RUSHDB_ENGINE_SCOPE |
no | Tenant on an engine started with --multitenant. |
Registry & autodiscovery
mcp.yamlat the repo root enables autodiscovery by MCP registriesglama.jsonat the repo root contains Glama metadata- Package:
@rushdb/mcp-server, command:npx
Development
git clone https://github.com/rush-db/mcp-server
cd mcp-server
npm install
npm run build
Troubleshooting: rushdb-mcp: command not found / MCP error -32000
This only happens when the MCP client launches the server with a working directory inside this repo (e.g. an .mcp.json at the repo root used by Claude Code / Cursor). This repo is @rushdb/mcp-server, so an unversioned npx @rushdb/mcp-server (even with -p) can resolve to the local package, whose rushdb-mcp bin isn't linked in node_modules/.bin. The process exits before the MCP handshake, which the client reports as -32000.
The published package is unaffected — the config above works as-is outside the repo. To run from inside the repo, pin a version so npx fetches from the registry instead of resolving the local package:
{
"mcpServers": {
"rushdb": {
"command": "npx",
"args": ["-y", "-p", "@rushdb/mcp-server@latest", "rushdb-mcp"],
"env": { "RUSHDB_API_KEY": "your-api-key-here" }
}
}
}
Alternatively, run the local build directly (uses your in-repo code, must be built first with npm run build):
{
"mcpServers": {
"rushdb": {
"command": "node",
"args": ["build/index.js"],
"env": { "RUSHDB_API_KEY": "your-api-key-here" }
}
}
}
License
Apache 2.0
RushDB MCP questions
How do I add RushDB MCP to Claude Code?
Run claude mcp add mcp-server -- npx -y @rushdb/mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add RushDB MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How do I use RushDB with Claude Desktop or Cursor?
For local stdio clients, obtain an API key from app.rushdb.com and add the @rushdb/mcp-server package to your MCP client configuration using npx.
Can I run RushDB without a Cloud account?
Yes, you can run a local standalone engine in direct mode by pointing a stdio MCP client at the local engine URL using the RUSHDB_MODE=direct environment variable.