hyperdb-mcp

library0.4.0jsnpmunverified

HyperDB MCP Server (v0.4.0) is an MCP (Model Context Protocol) server that turns Hyper, a columnar SQL database, into an instant analytics engine for LLM workflows. It provides zero-setup SQL analytics, ingesting data from JSON, CSV, Parquet, or Arrow formats and enabling query via SQL. Built on pure-Rust HyperDB, it achieves high ingest and query throughput (22M+ rows/sec insert, 18M+ rows/sec query). The server supports persistent databases for cross-session memory, shared daemon for multiple MCP clients, read-only mode, and inline chart generation. As a pre-1.0 release (0.x), it may undergo breaking changes frequently. Release cadence is rapid with multiple versions per month. Key differentiators: optimized for AI toolchains, combines structured queryable memory with columnar analytics, and features incremental ingest via watch directories.

database ai-ml

npm install hyperdb-mcp

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · HYPERDB-MCP

hyperdb-mcp

databasejavascriptv0.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Server

✓ import { Server } from '@modelcontextprotocol/sdk/server/index.js'

✗ const { Server } = require('@modelcontextprotocol/sdk');

Only available via ESM imports due to Node >= 21 requirement.

createServer

✓ import { createServer } from 'hyperdb-mcp'

✗ import createServer from 'hyperdb-mcp';

createServer is a named export, not default.

HyperProcess

✓ import { HyperProcess } from 'hyperdb-api'

✗ import { HyperProcess } from 'hyperdb-mcp';

HyperProcess is part of hyperdb-api package, not hyperdb-mcp.

Initializes the HyperDB MCP server, connects via stdio transport, and performs a basic ingest-and-query operation on a CSV file.

import { createServer } from 'hyperdb-mcp'; import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; const server = await createServer({ // Use environment variables for configuration hyperApiKey: process.env.HYPER_API_KEY ?? '' }); const transport = new StdioServerTransport(); await server.connect(transport); // Example: Ingest and query a CSV file const result = await server.processFile('/tmp/data.csv', 'SELECT COUNT(*) AS cnt FROM data'); console.log(result.rows);

Debug

Known issues

breakingPre-1.0 breaking changes: The 0.x line may undergo large breaking changes without notice. Public API not stable until 1.0.0.

fix

Pin version to current minor if relying on stable API; watch releases for migration guides.

affects: <1.0.0

gotchaRequires Node.js >= 21 (ESM-only). Older Node versions will fail with SyntaxError for import statements.

fix

Use Node 21+ or use a transpiler like esbuild to convert ESM to CommonJS.

affects: >=0.1.0

gotchaHyperProcess auto-starts; ensure Hyper is not already running on same port to avoid port conflicts.

fix

Set environment variable HYPER_PORT to a custom port or kill existing Hyper instance before launching.

affects: >=0.1.0

deprecatedThe watch_directory feature uses .ready sentinel files; this pattern may change in future releases.

fix

Monitor changelog for updated incremental ingest API.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Cannot find module '@modelcontextprotocol/sdk/server/stdio.js'

Missing MCP SDK dependency or incorrect import path.

fix

Install @modelcontextprotocol/sdk: npm install @modelcontextprotocol/sdk. For ESM, ensure import path ends with '.js'.

SyntaxError: Cannot use import statement outside a module

Package is ESM-only, but project is using CommonJS (require or no 'type':'module').

fix

Add 'type':'module' to package.json and use import statements. Or use Node 21+ and ensure .mjs extension.

HyperProcess Error: Address already in use

Port is already occupied by another Hyper instance or process.

fix

Set HYPER_PORT environment variable to an unused port. Check for existing Hyper processes: lsof -i :<port> and kill them.

Upgrade

Version history

0.4.0latest on npm

Audit

Dependencies

hyperdb-apirequiredCore Rust hyperdb-api crate provides the Hyper database engine.

@modelcontextprotocol/sdkrequiredMCP protocol implementation for server communication.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/tableau/hyper-api-rust ↗

packagehyperdb-mcp ↗

homepagehttps://github.com/tableau/hyper-api-rust/tree/main/hyperdb-mcp ↗