SuperDB MCP Server
SuperDB MCP Server enables AI assistants to work with SuperDB/SuperSQL by querying data, validating syntax, inspecting schemas, managing databases, and accessing docs/diagnostics.
Execute SuperSQL queries against files or inline data and return JSON, SUP, CSV, or table output.
Validate query syntax without executing, with diagnostics and migration suggestions.
Inspect a data file’s unique record shapes/types with counts and examples.
List, query, load into, and create SuperDB database pools/tables, optionally specifying a lake/database path and sort key.
Retrieve SuperDB documentation topics such as expert syntax and upgrade/migration guidance.
Check SuperDB version/environment/LSP status and compare two
superbinaries.Test a query across multiple SuperDB versions to detect breaking changes.
Use optional LSP-backed code completions and symbol documentation when
SUPERDB_LSP_PATHis set.
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., "@SuperDB MCP Server show me the schema of my users.csv file"
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.
SuperDB MCP Server
An MCP (Model Context Protocol) server for SuperDB that enables AI assistants to better compose SuperSQL queries, optionally backed by an LSP.
Table of Contents
Related MCP server: DuckDB MCP Server
About
SuperDB is the successor to zq from Brim Data. LLMs have limited knowledge of its syntax, so this MCP server provides the context AI assistants need to write correct queries.
Installation
Claude Code CLI
# Install for current project only
claude mcp add superdb -- npx -y superdb-mcp@latest
# Install for all projects (user scope)
claude mcp add --scope user superdb -- npx -y superdb-mcp@latestUsing @latest auto-upgrades the MCP server on each Claude launch. To pin a
specific version, replace @latest with a version number (e.g., @0.1.0).
Manual Configuration
Add to your Claude Code settings (~/.claude/settings.json) or project .mcp.json:
{
"mcpServers": {
"superdb": {
"command": "npx",
"args": ["-y", "superdb-mcp@latest"]
}
}
}Or install globally:
npm install -g superdb-mcp{
"mcpServers": {
"superdb": {
"command": "superdb-mcp"
}
}
}From Source
git clone https://github.com/chrismo/superdb-mcp.git
cd superdb-mcp
npm install
npm run build{
"mcpServers": {
"superdb": {
"command": "node",
"args": ["/path/to/superdb-mcp/dist/index.js"]
}
}
}LSP (Optional)
Only super_complete and super_docs use the LSP — query execution,
documentation, grok patterns, recipes, and database tools are fully
functional on their own. The
SuperDB LSP adds code completions
and symbol documentation for those who want it. Download a binary from the
releases page, then
point the MCP server to it:
export SUPERDB_LSP_PATH=/path/to/superdb-lspAdd the export to your shell profile for persistence. Run super_lsp_status
to verify setup.
Tools
Query & Data
super_query
Execute a SuperSQL query on data files. On errors, includes migration hints for
common zq-to-SuperDB syntax changes (yield→values, over→unnest, func→fn, etc.)
and SuperDB v0.4.0 changes (has→is_ok, quiet→ok, fields→paths,
max(a,b)→greatest, blend→fuse, |[...]|→set[...], ::time→::timestamp,
and more).
query: string # Required: The SuperSQL query
files?: string[] # Pipeline-style input (not for SQL FROM; use absolute paths in FROM)
data?: string # Inline data (alternative to files)
format?: string # Output: json (default), sup, csv, line, tsv, zeek
inputFormat?: string # Input format; needed for files without a recognized extension
static?: boolean # super -static: type-check all inputs (for SQL on JSON/CSV)As of SuperDB v0.4.0, a local file's format comes from its extension, so a file
without a recognized one needs inputFormat. SQL features like SELECT * and
alias-qualified joins need statically typed input; JSON and CSV are dynamic, so
set static: true for them.
Binary formats (bsup, db, parquet, arrows) are rejected: results
are returned as text, and binary output does not survive UTF-8 decoding. Use
line for undecorated scalar output. The table, jsup, and csup formats
were removed in SuperDB v0.4.0.
super_schema
Inspect types in a data file by finding unique shapes with counts and examples.
file: string # Path to data file
inputFormat?: string # Input format; needed for files without a recognized extensionDatabase
These tools target SuperDB v0.4.0+, where database pools became tables and
super db attach replaced super db auth/login and SUPER_DB. Each tool
takes an optional database (a path or URL, passed as super db -attach);
without it, super uses the database attached with super db attach. Create a
database with super db init <path>.
The pre-v0.4.0 parameter names pool and lake, and the tool name
super_db_create_pool, are still accepted.
super_db_query
Run a query or SQL statements against a database. Supports SQL CREATE TABLE,
CREATE SUPER TABLE, INSERT INTO, and DROP TABLE; separate statements with
;. Each statement returns a status record; if one fails, the records of the
statements before it are still returned.
query: string # The SuperSQL query or SQL statements
table?: string # Table (or table@branch) to read unless the query has a top-level FROM
database?: string # Database path or URL (default: attached database)
format?: string # Output: json (default), sup, csv, line, tsv, zeeksuper_db_list
List the tables in a database, with their sort keys.
database?: string # Database path or URL (default: attached database)super_db_create_table
Create a table. Tables are unsorted unless orderBy is set. With type, every
loaded value is cast to it, and a load is rejected if any value can't be cast.
name: string # Table name (`table` is accepted too)
orderBy?: string # Sort key, e.g. "ts:desc"
type?: string # SUP type, e.g. "{id:int64,msg:string}"
database?: string # Database path or URL (default: attached database)super_db_load
Load files or inline data into a table.
table: string # Table name
files?: string[] # Files to load
data?: string # Inline data
database?: string # Database path or URL (default: attached database)Documentation & Reference
Content comes from @chrismo/superkit
and targets the SuperDB release its docs declare (shown in each tool's
description). Responses include a version_note when the installed runtime
differs from the content target.
super_help
Get SuperDB documentation — expert guide, migration docs, or tutorials.
topic: string # "expert", "upgrade", "tutorials", or "tutorial:<name>"super_grok_patterns
Search/filter 89 grok patterns for parsing logs, timestamps, IPs, and more.
query?: string # Filter by pattern name or regex contentsuper_recipes
Search/list 16 recipe functions (from superkit) with signatures, descriptions, and examples.
query?: string # Filter by function name, description, or source fileEnvironment & Diagnostics
super_info
Get SuperDB version info, environment configuration, LSP availability, and installation instructions.
compare_to?: string # Optional path to another super binary to comparesuper_lsp_status
Check if the SuperDB LSP is installed and get installation instructions if not.
# No parameterssuper_test_compat
Test a query against multiple SuperDB versions to detect breaking changes.
query: string # The query to test
versions: string[] # Paths to different super binariesLSP Tools
Require SUPERDB_LSP_PATH environment variable to be set.
super_complete
Get code completions for a SuperSQL query at a cursor position.
query: string # The query text
line: number # Line number (0-based)
character: number # Character offset (0-based)super_docs
Get documentation for a symbol at a position in a query.
query: string # The query text
line: number # Line number (0-based)
character: number # Character offset (0-based)Example Usage
With the MCP server configured, Claude can execute queries like:
super_query({
query: "where status == 'active' | aggregate count() by category",
files: ["data.json"]
})No shell escaping needed - the query string is passed directly.
Requirements
Node.js 18+
superbinary in PATH:Homebrew:
brew install super(official)GitHub releases (official binaries)
asdf-superdb (community, versioned builds)
The database tools require SuperDB v0.4.0 or later
Versioning
This MCP server uses its own independent semver, decoupled from SuperDB's
version. Query tools (super_query, super_schema, etc.) work with any
version of the super binary, so the MCP server is useful even if your
runtime is older or newer than the target. Bundled content — documentation,
tutorials, grok patterns, and recipes — is written for a specific SuperDB
release, so aligning your runtime with the target version gives the best
results. The super_info tool reports both versions, and content tools
include a version_note when they differ.
The optional SuperDB LSP enables code completions and documentation lookup — see installation instructions.
MCP Version | SuperDB Target | Notes |
1.8.0 | v0.4.0 | Database tables, v0.4.0 migration hints |
1.1.0 | v0.1.0 | Grok patterns, tutorials, recipes from superkit |
1.0.0 | v0.1.0 | Switched to independent semver |
0.1.0 | v0.1.0 | Aligned with first official SuperDB release |
0.51231.x | 0.51231 (pre-release) | Legacy pseudo-version scheme |
License
This MCP server is licensed under the BSD-3-Clause License.
This project wraps SuperDB, which is
licensed under the
SuperDB Source Available License.
The MCP server does not distribute SuperDB source code or binaries; it invokes
a locally installed super binary at runtime.
Available Tools
13 toolssuper_completeB
Get code completions for a SuperSQL query at a position. Requires SUPERDB_LSP_PATH to be set.
Inputs: query (required), line (required), character (required).
super_db_create_poolC
Create a new pool in a SuperDB database.
Inputs: name (required), orderBy, lake.
super_db_listC
List all pools in a SuperDB database.
Inputs: lake.
super_db_loadC
Load data into a SuperDB database pool.
Inputs: pool (required), files, data, lake.
super_db_queryC
Query data from a SuperDB database pool.
Inputs: query (required), pool, lake, format.
super_docsB
Get documentation for a symbol at a position in a SuperSQL query. Requires SUPERDB_LSP_PATH to be set.
Inputs: query (required), line (required), character (required).
super_helpA
Get SuperDB documentation. Call this before writing complex queries or when migrating from zq or earlier versions of SuperDB. Topics: expert (syntax guide), upgrade (zq migration).
Inputs: topic (required).
super_infoA
Get SuperDB version info, environment configuration, LSP availability, and installation instructions. Call this to check setup status or learn how to install the optional LSP for enhanced query assistance.
Inputs: compare_to.
super_lsp_statusA
Check if the SuperDB LSP is installed and get installation instructions if not. The LSP enables code completions and documentation lookup for SuperSQL queries.
Inputs: no named parameters.
super_queryC
Execute a SuperDB/SuperSQL query on data files. Returns structured results without shell escaping issues.
Inputs: query (required), files, data, format, +1 more.
super_schemaB
Inspect the schema/types of a data file by finding all unique shapes (record types) with counts and examples.
Inputs: file (required).
super_test_compatB
Test a query against multiple SuperDB versions to detect syntax breaking changes. Useful for migration testing.
Inputs: query (required), versions (required).
super_validateA
Validate SuperSQL query syntax without executing. Returns diagnostics with position info and migration suggestions for common zq-to-SuperDB errors.
Inputs: query (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Most tools have distinct purposes, such as super_db_create_pool for pool creation and super_query for query execution, but there is some overlap between super_query and super_db_query (both involve querying data) and between super_docs and super_help (both provide documentation). The descriptions help clarify differences, but minor confusion could occur.
All tool names follow a consistent snake_case pattern with a 'super_' prefix, such as super_db_create_pool and super_validate. This uniformity makes the tool set predictable and easy to navigate, with no deviations in naming style.
With 13 tools, the count is well-scoped for a database server covering setup, querying, validation, and documentation. Each tool serves a specific function, such as super_info for setup checks and super_test_compat for migration testing, ensuring no redundancy or gaps in the core operations.
The tool set provides comprehensive coverage for SuperDB operations, including pool management (create, list, load), querying (query, validate), and setup assistance (info, lsp_status). Minor gaps exist, such as no explicit tools for updating or deleting pools, but core workflows like query execution and migration are well-supported.
Maintenance
Related MCP Connectors
Query Postgres, MySQL, SQL Server, Oracle, BigQuery, ClickHouse and Redshift from your AI client.
Explore, query, and inspect SQLite databases with ease. List tables, preview results, and view det…
Your Supabase account in natural language: run SQL, apply migrations, manage tables, storage, edge f
SQL validation, formatting, parsing, metadata extraction, linting, and security analysis.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with PostgreSQL and Supabase databases through natural language. Supports secure database operations including queries, migrations, and schema management with user-provided credentials.1-
- AlicenseBqualityFmaintenanceEnables AI assistants and IDEs to execute SQL queries on local DuckDB databases, in-memory databases, or cloud-stored databases with support for flexible connections and configurable result limits.11MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to query and explore SQLite databases through schema inspection, arbitrary SQL execution, and predefined canned queries. Compatible with Datasette metadata for enriching database structure with descriptions.145 PyPI28Apache 2.0
- AlicenseNot gradedqualityBmaintenanceQuery local CSV, Parquet, JSON and TSV files with real SQL via DuckDB. Gives your AI coding tool ground-truth data access instead of hallucinated answers.5MIT