MCP server for querying relational data stores with SQL, built on the squirreling async SQL engine.

Squirreling is a streaming SQL engine in pure JavaScript with no native dependencies. Three things about it shape what this MCP server can do:

• Async by design. Rows stream in and out of the planner; cells are evaluated lazily. Queries against remote data (HTTP-hosted parquet, Iceberg, postgres) start returning results before the underlying source is fully read, and large columns are only fetched when actually projected.
• Pluggable data sources. Anything that can implement squirreling's AsyncDataSource interface can be queried — files, object stores, REST APIs, databases. Adding a new source is a small adapter, not a fork. The server dispatches identifiers in the FROM clause to the right source by shape (file extension, URL pattern, bare name).
• Joins across disparate sources. Because every source is just an AsyncDataSource, a single query can JOIN a postgres table against a remote parquet file, or an Iceberg table against a local CSV, with no ETL or staging step. The engine handles the streaming join in-process.
• Lightweight deployment. Pure JavaScript, no native bindings, no daemon required. The same server runs as a long-lived HTTP service or as a stdio subprocess inside a local MCP client (Claude Desktop, Claude Code), so the query engine sits next to the model with zero infrastructure.

Supported sources:

• Parquet files (local paths and HTTP(S) URLs) via hyparquet
• Apache Iceberg tables via icebird
• CSV files (.csv)
• JSONL / NDJSON files (.jsonl, .ndjson)
• Postgres tables via pg (when DATABASE_URL is set)

The server exposes three tools:

• query — run a SQL statement; returns a markdown table.
• describe_table — return the schema of a single table without scanning rows.
• list_tables — enumerate tables/files available to query.

Tables in the FROM clause (and the table argument of describe_table) are dispatched by shape:

• file extension .parquet / .csv / .jsonl / .ndjson → file source
• contains a / (path or URL) → Iceberg table location
• otherwise (bare name like users or public.users) → postgres table, when DATABASE_URL is configured

Query results are returned as a markdown table.

Two transports are available:

npm install

# HTTP — server listens on a port, multiple clients can connect
npx squirreling-mcp --port 3000

# stdio — for local MCP clients (Claude Desktop, Claude Code, etc.)
npx squirreling-mcp --stdio

The HTTP transport speaks the MCP Streamable HTTP protocol at the root path; point your client at http://127.0.0.1:3000/. The stdio transport reads newline-delimited JSON-RPC on stdin and writes responses on stdout (logs go to stderr), so an MCP client config entry looks like:

{
  "mcpServers": {
    "squirreling": {
      "command": "npx",
      "args": ["-y", "squirreling-mcp", "--stdio"],
      "env": { "DATABASE_URL": "postgres://..." }  // optional
    }
  }
}

Configuration is read from environment variables at startup:

{
  "query": "SELECT * FROM \"https://s3.hyperparam.app/dataset.parquet\" LIMIT 10",
  "truncate": true            // optional, default true
}

• query — SQL string. Tables in FROM/JOIN clauses are file paths, http(s) URLs (quoted as identifiers), or bare postgres table names when DATABASE_URL is configured. Extension determines file format (.parquet, .csv, .jsonl, .ndjson); identifiers containing / are loaded as Iceberg tables; bare identifiers route to postgres.
• truncate — when true (default) string cells are capped at 1000 chars; when false, 10000. Truncated columns are marked (truncated) in the header.

Returns a markdown table preceded by a one-line summary (Query returned N rows in T seconds.). Output is capped at 100 rows.

{
  "table": "/path/to/file.parquet"   // or "users", or an Iceberg URL
}

• table — same syntax as a FROM-clause identifier in query.

Returns a short markdown block with the table's source, row count (when cheap), and a column listing with types where the source exposes them (parquet, iceberg, postgres) or just names (csv, jsonl).

{
  "path": "/data"                    // optional
}

• With no path: lists user tables in the configured postgres database (requires DATABASE_URL).
• With path set to a local directory: lists files whose extensions match a supported file source (.parquet, .csv, .jsonl, .ndjson). Subdirectories are not recursed.

Iceberg-warehouse and HTTP/S3 listings are not implemented; supply the explicit table URL to query or describe_table for those.

curl -sS -X POST http://127.0.0.1:3000/ \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'