# Scherlok

Scherlok profiles database tables, spots data anomalies, and can fail CI when a critical issue appears.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 11
- Author: rbmuller
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/rbmuller/scherlok
- Updated: 2026-10-19
- HTML: https://affpapa.org/en/nevibecode/mcp/scherlok

## What it 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.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `SCHERLOK_CONNECTION` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add scherlok -e SCHERLOK_CONNECTION=<SCHERLOK_CONNECTION> -- uvx scherlok
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from scherlok <command>

### Codex

**Platform CLI**
```bash
codex mcp add scherlok --env SCHERLOK_CONNECTION=<SCHERLOK_CONNECTION> -- uvx scherlok
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from scherlok <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e SCHERLOK_CONNECTION=<SCHERLOK_CONNECTION> scherlok uvx scherlok
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from scherlok <command>

## When to use it
- 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
- 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_project` after the models finish running.

## Similar
- [data-quality-frameworks](https://affpapa.org/en/nevibecode/skills/data-quality-frameworks.md) — skill · 11230 installs
- [dbt-sf-to-bq-translator](https://affpapa.org/en/nevibecode/skills/dbt-sf-to-bq-translator.md) — skill · 2300 installs
- [orionbelt-semantic-layer](https://affpapa.org/en/nevibecode/mcp/orionbelt-semantic-layer.md) — MCP server · ★ 101
- [sql-queries](https://affpapa.org/en/nevibecode/skills/sql-queries.md) — skill · 4500 installs
- [data-context-extractor](https://affpapa.org/en/nevibecode/skills/data-context-extractor.md) — skill · 3100 installs
- [YourMemory](https://affpapa.org/en/nevibecode/mcp/yourmemory.md) — MCP server · ★ 270

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md