CoraDB MCP Server

An MCP server for CoraDB. Any MCP client — an AI app such as Claude, an IDE, a script or another program — can use it to read a database's schema, run SELECTs (relational and SELECT … FROM MATCH graph queries) and run other statements, and get back exactly what the engine returns.

• Stateless. Every call names its database and carries its own login. The server opens a connection for the call, runs it, commits or rolls back, closes the connection and forgets the login. Nothing is kept between calls: no connection, no session, no password.

• One transaction per call. All statements of a call succeed and are committed together, or nothing is saved.

• The server setting has the last word. CORADB_WRITE_MODE decides whether changes can be saved at all; a call can only be stricter.

Quick start

Needs Node.js 20.6 or later and a running CoraDB. Nothing to install by hand: MCP clients start the server with npx, which downloads @coradb/coradb-mcp-server from npm the first time.

For the Claude desktop app: Settings → Developer → Edit Config, add this to mcpServers, then quit the app completely and reopen it:

"coradb": {
  "command": "npx",
  "args": ["-y", "@coradb/coradb-mcp-server"]
}

Then call a tool, for example execute_select with { "database": "e-commerce", "sql": "SELECT COUNT(*) FROM orders" }, or ask the AI in plain words: "How many orders are in e-commerce?"

After the server is updated, restart the client and start a new conversation: a conversation keeps the tool definitions it started with.

Contents: Quick start · How a call works · Tools · Transactions and write mode · Results · Using it from an AI app · Calling it directly · Settings · Installing and updating · Security · Development

Related MCP server: 多数据库 MCP Server

How a call works

Every database tool takes these login inputs:

Only host and port can be changed in the settings. Users and passwords are never stored by the server: a call that needs another user sends it.

For each call the server:

1. connects to the broker at host:port and logs in to database as user;

2. runs the statements one after the other, in one transaction (auto-commit is off);

3. commits, if the call may commit and every statement succeeded — otherwise rolls back;

4. closes the connection and drops the login.

Several databases, servers or users are simply different calls. If the connection breaks, times out or the server stops part-way, CoraDB rolls back whatever was not committed.

Tools

Inputs are strict: an input a tool does not know is refused (Unrecognized key) instead of being ignored, so a client with an outdated copy of a tool's definition finds out instead of being misunderstood.

All tools that take SQL accept several statements separated by ;. They run in order and the first error stops the call (later statements are reported as skipped). A ; inside a string, a quoted name or a comment does not split. If where a statement ends depends on server settings (for example a backslash before a quote), the call is refused: send the statements one per call.

connection_info

Logs in and reports the login used (user@host:port/database, never the password), the engine version, the round-trip time, the driver in use (version, folder, when it was loaded, how many times it was reloaded), the server's defaults, write mode and limits. Use it to check that a database is reachable.

{ "database": "e-commerce" }

describe_schema

The objects of the database as the given user sees them, read from the live catalog: tables, views, vertex (node) tables and edge tables, with columns, types, nullability, defaults, primary and foreign keys and indexes.

{ "database": "e-commerce", "object": "product" }

VERTEX TABLE DBA.product
  id INTEGER NOT NULL
  name VARCHAR(64) NOT NULL
  description VARCHAR(32) NOT NULL
  unit_price NUMERIC(10,2) NOT NULL
  units_in_stock SHORT NOT NULL
  PRIMARY KEY (id)

A kept copy is only handed out after the call's login succeeds.

execute_select

Runs one or more SELECTs and returns the columns and rows as the engine sends them. Each statement is first compiled by the server and refused, before anything runs, unless it is a SELECT. Nothing is ever committed.

{
  "database": "e-commerce",
  "sql": "SELECT c.name, COUNT(p) AS products FROM MATCH (p:product)-[:part_of]->(c:category) GROUP BY c.name ORDER BY products DESC LIMIT 3"
}

{
"login": "dba@localhost:33000/e-commerce",
"transaction": "rolled back",
"rolledBackBecause": "execute_select only reads",
"elapsedMs": 16,
"statements": [
{"statement":1,"sql":"SELECT c.name, COUNT(p) AS products FROM MATCH …","type":"SELECT","columns":[{"name":"c.name","type":"String","nullable":false,"precision":32,"scale":0},{"name":"products","type":"Int","nullable":false,"precision":10,"scale":0}],"totalRows":3,"truncated":false,"elapsedMs":15, "rows": [
  ["Hoodies & Sweatshirts",390],
  ["Tees",385],
  ["Jackets",362]
]}
]
}

execute_sql

Runs any statements — INSERT, UPDATE, DELETE, MERGE, CREATE, ALTER, DROP, SELECT … — in one transaction. Not offered when CORADB_WRITE_MODE=off.

{
  "database": "e-commerce",
  "sql": "UPDATE product SET units_in_stock = 40 WHERE id = 15"
}

{
"login": "dba@localhost:33000/e-commerce",
"transaction": "committed",
"elapsedMs": 21,
"statements": [
{"statement":1,"sql":"UPDATE product SET units_in_stock = 40 WHERE id = 15","type":"UPDATE","affectedRows":1,"elapsedMs":12}
]
}

The same call with "dryRun": true returns "transaction": "rolled back", "rolledBackBecause": "dryRun was requested" and still reports "affectedRows": 1: what would have changed. COMMIT and ROLLBACK statements are refused — the call controls the transaction. Serial increments (AUTO_INCREMENT, NEXT_VALUE) are not undone by a rollback; everything else, DDL included, is.

explain_query

The plan CoraDB's optimizer chooses for each SELECT of the call, without running it (statements other than SELECT are not explained).

{ "database": "e-commerce", "sql": "SELECT c.name FROM MATCH (p:product)-[:part_of]->(c:category)" }

Transactions and write mode

What happens at the end of an execute_sql call:

A call can only be stricter than the server, never less strict. If any statement fails, the time limit runs out or the call is cancelled, everything is rolled back. The reply's transaction says committed or rolled back, and rolledBackBecause says why.

Results

execute_select and execute_sql reply with one JSON document: the login, transaction, rolledBackBecause, stopped (error, timeout or cancelled, when the call stopped early), elapsedMs, and per statement: type (as the server compiled it), sql, columns (name, type, precision, scale, nullable, table), rows (one array per row), totalRows, truncated, affectedRows, error (code and message from the engine) or skipped.

Values: numbers, strings, null, booleans. DATE as YYYY-MM-DD, DATETIME as YYYY-MM-DD HH:MM:SS.mmm, TIMESTAMP as YYYY-MM-DD HH:MM:SS (the stored wall-clock time, no time-zone shift). NUMERIC values that do not fit a JavaScript number exactly come back as text. Binary values and graph objects the driver does not decode come back as hex. BLOB/CLOB show their type and length only. Strings longer than CORADB_MAX_CELL_CHARS are cut; rows beyond CORADB_MAX_RESPONSE_CHARS are left out and counted in rowsOmittedForSize.

A call that stops early, and any other failure, is returned as a tool error (isError: true): engine errors as CoraDB error <code>: <message>, an unreachable broker as Could not work with CoraDB at host:port ….

Time limits and cancelling. Every call has a time limit (timeoutMs, or CORADB_CALL_TIMEOUT_MS, at most CORADB_MAX_TIMEOUT_MS), also given to CoraDB as the statement's query timeout. When it runs out, or the client cancels the call (MCP notifications/cancelled), the running statement is cancelled on the server, the rest are skipped and everything is rolled back.

Using it from an AI app

Claude desktop app (and Cowork). Settings → Developer → Edit Config, add to mcpServers, then quit the app completely (also from the system tray) and start it again. Settings go in env; leave out the ones you do not change:

"coradb": {
  "command": "npx",
  "args": ["-y", "@coradb/coradb-mcp-server"],
  "env": { "CORADB_HOST": "localhost", "CORADB_PORT": "33000", "CORADB_WRITE_MODE": "write" }
}

If the app cannot start npx on Windows, use "command": "cmd", "args": ["/c", "npx", "-y", "@coradb/coradb-mcp-server"].

Claude Code:

claude mcp add coradb --scope user -- npx -y @coradb/coradb-mcp-server

Any other MCP client: run npx -y @coradb/coradb-mcp-server (or coradb-mcp-server after a global install) as a stdio server; settings go in its environment.

Ask in plain words; the AI turns the request into calls. For example:

Calling it directly

The server speaks MCP (JSON-RPC 2.0) over stdin/stdout, one JSON message per line. A program starts it, initializes, and calls tools:

→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-app","version":"1.0"}}}
← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","serverInfo":{"name":"coradb",…},…}}
→ {"jsonrpc":"2.0","method":"notifications/initialized"}
→ {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"execute_select","arguments":{"database":"e-commerce","sql":"SELECT COUNT(*) FROM orders"}}}
← {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"{\n\"login\": …"}]}}

With the MCP TypeScript SDK (Node.js):

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const client = new Client({ name: 'my-app', version: '1.0.0' });
await client.connect(new StdioClientTransport({
  command: 'npx',
  args: ['-y', '@coradb/coradb-mcp-server'],
}));

const r = await client.callTool({
  name: 'execute_sql',
  arguments: {
    database: 'e-commerce',
    user: 'dba',
    password: '',
    sql: 'UPDATE product SET units_in_stock = 40 WHERE id = 15',
    dryRun: true,
  },
});
const result = JSON.parse(r.content[0].text);   // { login, transaction, statements: [...] }
console.log(result.transaction, result.statements[0].affectedRows);

await client.close();

scripts/smoke.mjs and test/db/live.test.mjs in the source repository are complete examples.

Settings

Environment variables, from the env block of the client's configuration. When the server runs from a source checkout, they can also come from .env in its folder (.env.example, included in the package, lists them all); the environment wins over .env, and only CORADB_* variables are read from it. Restart the client after a change. connection_info shows which came from .env (names only).

Installing and updating

• With npx (recommended): nothing to install. npx downloads the package the first time and may keep using that copy; to always start the newest version use @coradb/coradb-mcp-server@latest in args, and to pin one, for example @coradb/coradb-mcp-server@1.0.0.

• Global install: npm install -g @coradb/coradb-mcp-server, then use "command": "coradb-mcp-server" with no args. Update with npm update -g @coradb/coradb-mcp-server.

• The CoraDB driver is the npm package @coradb/node-coradb, installed with the server. When its files change (an update), the server loads the new version before the next call, with no restart. If the new code does not load, the previous version keeps working and connection_info shows the error under driver.reloadError; connection_info also shows the driver's version, folder, load time and number of reloads.

Security

• No stored logins. The server keeps no users or passwords, in files or in memory between calls; each call brings its own and it is dropped when the call ends. Replies and connection_info never show passwords.

• The client holds the credentials. Whoever calls the server sends the password. When the caller is an AI app, the AI sees the password it sends.

• CoraDB's rights apply. A call can do exactly what its user may do in that database. Use a user with only SELECT rights for reading.

• Guards. execute_select and explain_query let the server compile each statement and refuse anything that is not a SELECT before it runs. COMMIT/ROLLBACK statements are refused. CORADB_WRITE_MODE=dryrun or off prevents saving whatever a call asks.

• Local only. The server talks to its client over stdio on the same computer; it opens no network port of its own.

Development

git clone https://github.com/apsisware/coradb-mcp-server.git && cd coradb-mcp-server
npm install          # installs and builds dist/
npm test             # unit tests, no database needed
npm run test:db      # live tests against e-commerce on localhost:33000 as dba

To run a local build from a client, use "command": "node" with "args": ["<path to the checkout>/dist/index.js"].

Files