warehouse-mcp

library0.4.2jsnpmunverified

Production-ready MCP (Model Context Protocol) server for data warehouses. Supports Postgres, Oracle, Snowflake, BigQuery, Redshift, DuckDB, and MotherDuck with read-only enforcement, four-tier role-based access, optional warehouse-role impersonation (SET ROLE for native RLS/CLS), JSONL audit log, and optional output PII masking. Self-host via Docker or npx. Current version 0.4.2, released monthly. Differentiators: dialect-aware read-only validation, per-key RLS mapping, 13 tools including column profiling and time-series bucketing.

database ai-ml

npm install warehouse-mcp

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WAREHOUSE-MCP

warehouse-mcp

databasejavascriptv0.4.2

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.

warehouse-mcp

✓ npx @kalehdoo/warehouse-mcp

✗ npm install -g warehouse-mcp

Package is not on npm as 'warehouse-mcp'; use npx with the scoped name. Run as a CLI, not imported.

Docker image

✓ docker pull ghcr.io/kalehdoo/warehouse-mcp:latest

✗ docker pull warehouse-mcp

Image is hosted on GitHub Container Registry, not Docker Hub. Tag with version or 'latest'.

Configuration via environment variables

✓ WAREHOUSE_TYPE=postgres WAREHOUSE_HOST=localhost WAREHOUSE_PORT=5432 MCP_API_KEYS=key1:reader MCP_AUDIT_LOG_PATH=/var/log/warehouse-mcp/audit.jsonl

✗ Using a config file or CLI flags; only env vars supported at startup

All configuration is through environment variables for security and Docker compatibility. No config file support.

Start warehouse-mcp server via Docker Compose and configure Claude Desktop to connect to it.

docker compose up # Or manually: # docker run -p 3001:3001 \ # -e WAREHOUSE_TYPE=postgres \ # -e WAREHOUSE_HOST=localhost \ # -e WAREHOUSE_PORT=5432 \ # -e WAREHOUSE_DATABASE=mydb \ # -e WAREHOUSE_USER=user \ # -e WAREHOUSE_PASSWORD=pass \ # -e MCP_API_KEYS=key1:reader \ # -e MCP_AUDIT_LOG_PATH=/var/log/audit.jsonl \ # ghcr.io/kalehdoo/warehouse-mcp:0.4.2 # Claude Desktop config: # { # "mcpServers": { # "warehouse": { # "command": "npx", # "args": ["@kalehdoo/warehouse-mcp"], # "env": { # "WAREHOUSE_TYPE": "postgres", # "WAREHOUSE_HOST": "localhost", # "WAREHOUSE_PORT": "5432", # "WAREHOUSE_DATABASE": "mydb", # "WAREHOUSE_USER": "user", # "WAREHOUSE_PASSWORD": "pass", # "MCP_API_KEYS": "key1:reader" # } # } # } # }

Debug

Known issues

breakingv0.3.0 renamed environment variable 'DATABASE_URL' to 'WAREHOUSE_DATABASE_URL' and split into individual WAREHOUSE_* vars. Old format ignored with no error.

fix

Replace any 'DATABASE_URL' with 'WAREHOUSE_*' variables as per docs.

affects: <0.3.0

breakingv0.4.0 changed the MCP API key format from 'key:role:warehouse_role' to 'key:role[:set_role=warehouse_role]'. Old colons may be misinterpreted.

fix

Update MCP_API_KEYS entries to use 'set_role=' prefix for warehouse role instead of third colon-separated value.

affects: <0.4.0

gotchaThe 'query' tool validates SELECT only at the SQL level, but some warehouses (e.g., Snowflake) support multi-statement queries with ';' separator. The validator may allow ';' but only the first statement is executed, silently ignoring subsequent DML.

fix

Do not rely on 'query' tool to block multi-statement input; ensure client-side validation or use a restricted DB user.

affects: >=0.1.0

deprecatedThe 'query' tool deprecates replacing 'table' parameter (removed in v0.4.0) with generic SQL; update any clients.

fix

Use the 'query' tool with full SQL statement instead of the removed 'table' convenience parameter.

affects: >=0.4.0

gotchaPII masking only works on columns explicitly defined in configuration; it does not automatically detect or mask PII in free text or nested JSON.

fix

Manually define all PII columns in the 'PII_COLUMNS' environment variable; test with sensitive data before production use.

affects: >=0.2.0

Errors

Common errors & fixes

Error: Cannot find module '@kalehdoo/warehouse-mcp'

Attempting to require/import the package as a library instead of running it as a CLI via npx.

fix

Run via npx: npx @kalehdoo/warehouse-mcp (no install required).

MCP handshake failed: timeout

MCP SDK transport timeout; usually due to slow database connection startup or incorrect WAREHOUSE_* env vars.

fix

Verify all WAREHOUSE_* environment variables are set correctly; ensure database is reachable; increase transport timeout in MCP client config.

Role 'reader' not allowed to execute tool 'query'

Misconfigured MCP_API_KEYS; the key used has a lower role than required for the tool.

fix

Check MCP_API_KEYS variable and assign appropriate role (e.g., 'admin' for full access).

SQL validation error: Only SELECT statements are allowed.

The 'query' tool's validator rejected a non-SELECT statement (e.g., INSERT, UPDATE, DELETE, DDL).

fix

The tool enforces read-only; use only SELECT statements or check your application logic.

Upgrade

Version history

0.4.2latest on npm

Audit

Dependencies

@modelcontextprotocol/sdkrequiredMCP SDK for server framework

knexrequiredDatabase query builder for multi-dialect support

pinorequiredStructured logging and audit log

Agent activity

35 hits · last 30 days

node