BlazeSQL MCP Server

BlazeSQL MCP Server

blaze-sql-server is a secure-by-default MCP server and CLI for the BlazeSQL natural-language query API.

It supports two modes:

• serve: run as an MCP stdio server for Cursor, Claude Desktop, Codex, and other MCP clients
• query: execute a single BlazeSQL request directly from the shell

Highlights

• MCP tool: exposes blazesql_query
• CLI commands: serve, query, doctor, help, version
• Security defaults: HTTPS-only remote endpoints, bounded timeouts, redacted logging, capped formatted output
• Validation: runtime config validation plus BlazeSQL response-shape validation
• Tooling: pnpm, CI, automated tests, and project-level mcporter config

Requirements

• Node.js >=20.11.0
• pnpm >=10
• A BlazeSQL API key

Install

pnpm install
cp .env.sample .env

Set at least:

BLAZE_API_KEY=YOUR_API_KEY_HERE

Optional environment variables:

• BLAZE_API_ENDPOINT
• BLAZE_REQUEST_TIMEOUT_MS
• BLAZE_MAX_RESPONSE_CHARS
• BLAZE_LOG_LEVEL
• BLAZE_ALLOW_INSECURE_ENDPOINT

Build

pnpm build

Run As MCP Server

For backward compatibility, running the binary with no arguments starts the stdio server:

node build/index.js

Explicitly:

node build/index.js serve

The exposed MCP tool is:

• blazesql_query
• db_id: BlazeSQL database ID
• natural_language_request: the prompt to send to BlazeSQL

Use With MCPorter

MCPorter can discover this server automatically via the project-level config at config/mcporter.json.

From the project root:

npx mcporter list
npx mcporter call blazesql.blazesql_query db_id:"your_db_id" natural_language_request:"show me total users"

Ad hoc usage from anywhere:

npx mcporter call --stdio "node /path/to/blaze-sql-mcp-server/build/index.js" --name blazesql blazesql.blazesql_query db_id:"your_db_id" natural_language_request:"total sales last month"

Run As CLI

Print help:

node build/index.js --help

Run a direct query:

node build/index.js query --db-id db_demo --request "show me total users by city"

Use positional arguments:

node build/index.js query db_demo "show me total users by city"

Read the request from stdin:

printf 'show me total users by city\n' | node build/index.js query db_demo --stdin

Available output formats:

node build/index.js query db_demo "show me total users by city" --format markdown
node build/index.js query db_demo "show me total users by city" --format text
node build/index.js query db_demo "show me total users by city" --format json

Diagnostics

Check runtime configuration:

node build/index.js doctor
node build/index.js doctor --json

doctor is safe to run in shared terminals: it never prints the raw API key.

Validate

pnpm typecheck
pnpm test
pnpm check

MCP Client Configuration

Example stdio command:

/absolute/path/to/node /absolute/path/to/blaze-sql-mcp-server/build/index.js

Because the binary defaults to serve, MCP clients do not need an extra subcommand.

Design Notes

The CLI shape intentionally follows the same single-purpose command pattern popularized by tools like mcporter: a predictable command surface, direct shell usage, and one obvious machine-readable mode where it matters.