{"id":44123,"library":"warehouse-mcp","title":"warehouse-mcp","description":"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.","status":"active","version":"0.4.2","language":"javascript","source_language":"en","source_url":"https://github.com/kalehdoo/warehouse-mcp","tags":["javascript","mcp","model-context-protocol","postgres","oracle","snowflake","bigquery","redshift","duckdb"],"install":[{"cmd":"npm install warehouse-mcp","lang":"bash","label":"npm"},{"cmd":"yarn add warehouse-mcp","lang":"bash","label":"yarn"},{"cmd":"pnpm add warehouse-mcp","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"MCP SDK for server framework","package":"@modelcontextprotocol/sdk","optional":false},{"reason":"Database query builder for multi-dialect support","package":"knex","optional":false},{"reason":"Structured logging and audit log","package":"pino","optional":false}],"imports":[{"note":"Package is not on npm as 'warehouse-mcp'; use npx with the scoped name. Run as a CLI, not imported.","wrong":"npm install -g warehouse-mcp","symbol":"warehouse-mcp","correct":"npx @kalehdoo/warehouse-mcp"},{"note":"Image is hosted on GitHub Container Registry, not Docker Hub. Tag with version or 'latest'.","wrong":"docker pull warehouse-mcp","symbol":"Docker image","correct":"docker pull ghcr.io/kalehdoo/warehouse-mcp:latest"},{"note":"All configuration is through environment variables for security and Docker compatibility. No config file support.","wrong":"Using a config file or CLI flags; only env vars supported at startup","symbol":"Configuration via environment variables","correct":"WAREHOUSE_TYPE=postgres\nWAREHOUSE_HOST=localhost\nWAREHOUSE_PORT=5432\nMCP_API_KEYS=key1:reader\nMCP_AUDIT_LOG_PATH=/var/log/warehouse-mcp/audit.jsonl"}],"quickstart":{"code":"docker compose up\n# Or manually:\n# docker run -p 3001:3001 \\\n#   -e WAREHOUSE_TYPE=postgres \\\n#   -e WAREHOUSE_HOST=localhost \\\n#   -e WAREHOUSE_PORT=5432 \\\n#   -e WAREHOUSE_DATABASE=mydb \\\n#   -e WAREHOUSE_USER=user \\\n#   -e WAREHOUSE_PASSWORD=pass \\\n#   -e MCP_API_KEYS=key1:reader \\\n#   -e MCP_AUDIT_LOG_PATH=/var/log/audit.jsonl \\\n#   ghcr.io/kalehdoo/warehouse-mcp:0.4.2\n# Claude Desktop config:\n# {\n#   \"mcpServers\": {\n#     \"warehouse\": {\n#       \"command\": \"npx\",\n#       \"args\": [\"@kalehdoo/warehouse-mcp\"],\n#       \"env\": {\n#         \"WAREHOUSE_TYPE\": \"postgres\",\n#         \"WAREHOUSE_HOST\": \"localhost\",\n#         \"WAREHOUSE_PORT\": \"5432\",\n#         \"WAREHOUSE_DATABASE\": \"mydb\",\n#         \"WAREHOUSE_USER\": \"user\",\n#         \"WAREHOUSE_PASSWORD\": \"pass\",\n#         \"MCP_API_KEYS\": \"key1:reader\"\n#       }\n#     }\n#   }\n# }","lang":"typescript","description":"Start warehouse-mcp server via Docker Compose and configure Claude Desktop to connect to it."},"warnings":[{"fix":"Replace any 'DATABASE_URL' with 'WAREHOUSE_*' variables as per docs.","message":"v0.3.0 renamed environment variable 'DATABASE_URL' to 'WAREHOUSE_DATABASE_URL' and split into individual WAREHOUSE_* vars. Old format ignored with no error.","severity":"breaking","affected_versions":"<0.3.0"},{"fix":"Update MCP_API_KEYS entries to use 'set_role=' prefix for warehouse role instead of third colon-separated value.","message":"v0.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.","severity":"breaking","affected_versions":"<0.4.0"},{"fix":"Do not rely on 'query' tool to block multi-statement input; ensure client-side validation or use a restricted DB user.","message":"The '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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use the 'query' tool with full SQL statement instead of the removed 'table' convenience parameter.","message":"The 'query' tool deprecates replacing 'table' parameter (removed in v0.4.0) with generic SQL; update any clients.","severity":"deprecated","affected_versions":">=0.4.0"},{"fix":"Manually define all PII columns in the 'PII_COLUMNS' environment variable; test with sensitive data before production use.","message":"PII masking only works on columns explicitly defined in configuration; it does not automatically detect or mask PII in free text or nested JSON.","severity":"gotcha","affected_versions":">=0.2.0"}],"env_vars":null,"search_vec":"'0.4.2':63 '13':79 'access':35 'audit':47 'awar':69 'base':34 'bigqueri':19,98 'bucket':88 'column':82 'context':9,93 'current':61 'data':13 'dialect':68 'dialect-awar':67 'differenti':66 'docker':58 'duckdb':21,100 'enforc':28 'four':30 'four-tier':29 'host':56 'imperson':40 'includ':81 'javascript':89 'jsonl':46 'key':76 'log':48 'map':78 'mask':53 'mcp':3,7,90 'model':8,92 'model-context-protocol':91 'month':65 'motherduck':23 'nativ':44 'npx':60 'option':36,50 'oracl':17,96 'output':51 'per':75 'per-key':74 'pii':52 'postgr':16,95 'product':5 'production-readi':4 'profil':83 'protocol':10,94 'read':26,71 'read-on':25,70 'readi':6 'redshift':20,99 'releas':64 'rls':77 'rls/cls':45 'role':33,39,42 'role-bas':32 'self':55 'self-host':54 'seri':87 'server':11 'set':41 'snowflak':18,97 'support':15 'tier':31 'time':86 'time-seri':85 'tool':80 'valid':73 'version':62 'via':57 'warehous':2,14,38 'warehouse-mcp':1 'warehouse-rol':37","created_at":"2026-06-05T17:03:05.583747+00:00","updated_at":"2026-06-05T17:03:05.583747+00:00","problems":[{"fix":"Run via npx: npx @kalehdoo/warehouse-mcp (no install required).","cause":"Attempting to require/import the package as a library instead of running it as a CLI via npx.","error":"Error: Cannot find module '@kalehdoo/warehouse-mcp'"},{"fix":"Verify all WAREHOUSE_* environment variables are set correctly; ensure database is reachable; increase transport timeout in MCP client config.","cause":"MCP SDK transport timeout; usually due to slow database connection startup or incorrect WAREHOUSE_* env vars.","error":"MCP handshake failed: timeout"},{"fix":"Check MCP_API_KEYS variable and assign appropriate role (e.g., 'admin' for full access).","cause":"Misconfigured MCP_API_KEYS; the key used has a lower role than required for the tool.","error":"Role 'reader' not allowed to execute tool 'query'"},{"fix":"The tool enforces read-only; use only SELECT statements or check your application logic.","cause":"The 'query' tool's validator rejected a non-SELECT statement (e.g., INSERT, UPDATE, DELETE, DDL).","error":"SQL validation error: Only SELECT statements are allowed."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/kalehdoo/warehouse-mcp#readme","github":"https://github.com/kalehdoo/warehouse-mcp","docs":null,"changelog":null,"pypi":null,"npm":"warehouse-mcp","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","ai-ml"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}