Scherlok — Claude Code MCP server: what it does, how to install
Scherlok profiles database tables, spots data anomalies, and can fail CI when a critical issue appears.
claude mcp add scherlok -e SCHERLOK_CONNECTION=<SCHERLOK_CONNECTION> -- uvx scherlokWhat Scherlok does
Scherlok connects to PostgreSQL, BigQuery, Snowflake, MySQL, or DuckDB and records table characteristics such as row volume, column types, NULL rates, freshness, distributions, and cardinality. It keeps the collected profiles in a local SQLite store. Once five valid profiles exist, later checks can use variation learned from the latest 30 profiles.
The workflow has three commands: connect opens the database connection, investigate builds the profiles, and watch checks for changes. ci combines the process for pipeline use. Detectors cover volume changes, schema drift, NULL surges, distribution shifts, stale tables, and sudden growth in distinct values.
Alerts can go to Slack, Discord, Teams, or a generic HTTP endpoint. With --exit-code --fail-on critical, a critical finding becomes a CI failure. The dbt integration requires scherlok[dbt] and reads target/manifest.json together with profiles.yml. MCP setup requires SCHERLOK_CONNECTION; without it, the database connection is not configured.
What it helps with
- profile warehouse tables
- catch sudden row-count changes
- detect schema drift and NULL spikes
- flag stale database tables
- fail CI on critical data anomalies
Example prompts for the agent
- Ask Scherlok to inspect the database and report critical anomalies.
- Compare the current tables with their learned profiles and find freshness issues.
- Check the dbt project at
./my_dbt_projectafter the models finish running.
How to install Scherlok
Platform CLI
claude mcp add scherlok -e SCHERLOK_CONNECTION=<SCHERLOK_CONNECTION> -- uvx scherlokReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from scherlok <command>
Platform CLI
codex mcp add scherlok --env SCHERLOK_CONNECTION=<SCHERLOK_CONNECTION> -- uvx scherlokReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from scherlok <command>
Config file
{
"mcpServers": {
"scherlok": {
"command": "uvx",
"args": [
"scherlok"
],
"env": {
"SCHERLOK_CONNECTION": "<SCHERLOK_CONNECTION>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from scherlok <command>
Config file
{
"servers": {
"scherlok": {
"type": "stdio",
"command": "uvx",
"args": [
"scherlok"
],
"env": {
"SCHERLOK_CONNECTION": "<SCHERLOK_CONNECTION>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from scherlok <command>
Platform CLI
gemini mcp add -e SCHERLOK_CONNECTION=<SCHERLOK_CONNECTION> scherlok uvx scherlokReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from scherlok <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Scherlok
How do I install Scherlok in Claude Code?
Run claude mcp add scherlok -e SCHERLOK_CONNECTION=<SCHERLOK_CONNECTION> -- uvx scherlok.
What does Scherlok do?
It learns table profiles and then detects changes in volume, schema, NULL rates, distributions, freshness, and cardinality. Findings can be used as a CI gate.
Which databases does Scherlok support?
The listed connectors cover PostgreSQL, BigQuery, Snowflake, MySQL, and DuckDB. dbt projects use the separate scherlok[dbt] installation.
