What can you do with this server?

The SuperDB MCP Server enables AI assistants to interact with SuperDB by executing SuperSQL queries, managing databases, accessing documentation, and leveraging optional LSP-powered code assistance. * Query Execution: Run SuperSQL queries on data files or inline data (super_query) or database pools (super_db_query), with output in JSON, SUP, CSV, or table formats * Query Validation: Check SuperSQL syntax without executing, with diagnostics and migration hints for zq-to-SuperDB changes (super_validate) * Schema Inspection: Analyze data files to discover unique record shapes with counts and examples (super_schema) * Database Management: List pools, create new pools, and load data into a SuperDB lake (super_db_list, super_db_create_pool, super_db_load) * Documentation & Reference: Access expert syntax guides, upgrade/migration docs, grok patterns, and recipe functions (super_help, super_grok_patterns, super_recipes) * Environment Diagnostics: Get version info, environment configuration, LSP availability, and optionally compare two super binaries (super_info, super_lsp_status) * Cross-Version Compatibility Testing: Run queries against multiple SuperDB versions to detect breaking changes (super_test_compat) * LSP-Powered Code Assistance (requires optional SuperDB LSP): Get autocompletions at a cursor position (super_complete) and inline symbol documentation (super_docs)

How do I use SuperDB MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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.

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@latest

Using @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 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-lsp

Add 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.).

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, table inputFormat?: string # Force input format

`super_schema`

Inspect types in a data file by finding unique shapes with counts and examples.

file: string # Path to data file

Database (Lake)

`super_db_query`

Query data from a database pool.

query: string # The SuperSQL query pool?: string # Pool name lake?: string # Lake path format?: string # Output format

`super_db_list`

List all pools in a SuperDB database.

lake?: string # Lake path (default: ~/.super)

`super_db_create_pool`

Create a new pool.

name: string # Pool name orderBy?: string # Sort key lake?: string # Lake path

`super_db_load`

Load data into a pool.

pool: string # Pool name files?: string[] # Files to load data?: string # Inline data lake?: string # Lake path

Documentation & Reference

Content targets SuperDB v0.1.0. 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 content

`super_recipes`

Search/list 16 recipe functions (from superkit) with signatures, descriptions, and examples.

query?: string # Filter by function name, description, or source file

Environment & Diagnostics

`super_info`

Get SuperDB version info, environment configuration, LSP availability, and installation instructions.

compare_to?: string # Optional path to another super binary to compare

`super_lsp_status`

Check if the SuperDB LSP is installed and get installation instructions if not.

# No parameters

`super_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 binaries

LSP 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+
super binary in PATH:
- Homebrew (official, latest build)
- asdf-superdb (community, versioned builds)

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.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

BSD 3-Clause License

Install Server

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

Resources

Need Help?

Report Issue

Related Servers

Tools

View all tools

SuperDB MCP Server

SuperDB MCP Server

Table of Contents

About

Installation

Claude Code CLI

Manual Configuration

From Source

LSP (Optional)

Tools

Query & Data

`super_query`

`super_schema`

Database (Lake)

`super_db_query`

`super_db_list`

`super_db_create_pool`

`super_db_load`

Documentation & Reference

`super_help`

`super_grok_patterns`

`super_recipes`

Environment & Diagnostics

`super_info`

`super_lsp_status`

`super_test_compat`

LSP Tools

`super_complete`

`super_docs`

Example Usage

Requirements

Versioning

License

Resources

Tools

Latest Blog Posts

MCP directory API