dqsleuth

dqsleuth is an MCP server for investigating data quality problems. It gives Claude (or any MCP client) read-only tools to find out why the data is wrong, not just that a test failed.

Ask it things like:

• "Revenue dropped 35% yesterday. Is that real?"

• "Why does joining orders to customers give me more rows than orders has?"

• "Our unique test on stg_orders is failing. Where did it break and what does it affect?"

It runs locally on DuckDB. It reads CSV, Parquet and NDJSON files, DuckDB databases (including a dbt-duckdb warehouse), an optional Postgres database, and dbt's target/ artifacts. It never writes to any of them.

Install

Claude Code (plugin)

/plugin install dqsleuth --marketplace tripleaceme/dqsleuth

On Claude Code older than 2.1.275, add the marketplace first:

/plugin marketplace add tripleaceme/dqsleuth
/plugin install dqsleuth@dqsleuth

The plugin bundles the MCP server and an /dqsleuth:investigate skill. The skill gives Claude a structured method: hypotheses, evidence, root cause, fix, prevention. It needs uv on your PATH, because the server runs through uvx.

Any other MCP client

{
  "mcpServers": {
    "dqsleuth": {
      "command": "uvx",
      "args": ["dqsleuth", "--root", "/path/to/your/project"]
    }
  }
}

Or install it with pip install dqsleuth and run dqsleuth --root ..

Related MCP server: mcp-duckdb-analyst

Try it on the demo data

The repo ships a small shop dataset with six planted faults. Clone it, open Claude Code in examples/shop, and ask:

/dqsleuth:investigate revenue on 30 Oct 2026 dropped. Is it real?

Claude should find that Paystack payments are completely missing that day. That makes it a feed problem, not lost sales. Along the way it should also find the 25 orders that were loaded twice and the two failing dbt tests. The faults are listed at the top of examples/make_demo.py, and tests/test_engine.py checks that dqsleuth finds each one.

Tools

There is also an investigate MCP prompt for clients that support prompts.

Configuration

On start, dqsleuth scans the root up to four levels deep. It registers up to 60 data files and finds target/manifest.json. It skips .git, virtualenvs, node_modules and dbt_packages. dbt artifacts are re-read whenever dbt rewrites them, so a new dbt build shows up without a restart.

The Claude Code plugin sets the root to your project directory. To point it at Postgres, export DQSLEUTH_POSTGRES_URL before starting Claude Code. Use a read-only database role.

Safety

dqsleuth is built to be safe to hand to an agent:

• No writes. Files are exposed as views. DuckDB databases and Postgres are attached READ_ONLY. dq_run_sql rejects anything that isn't a single SELECT.

• No reads outside the project. After start-up, DuckDB's external access is switched off for everything except the project root and paths you passed with --source. A query like read_text('~/.ssh/id_rsa') fails, and the setting cannot be switched back on the live connection.

• No SQL injection through names. Table and column names are checked against the catalog before they go into SQL.

• No secrets in results. The Postgres password goes to libpq through PGPASSWORD, so it never appears in the connection string that a SELECT could see.

• No network calls, except installing DuckDB's Postgres extension the first time you use Postgres.

Results are capped (limit on every listing tool) so a large table can't flood the agent's context.

Development

uv sync
uv run python examples/make_demo.py
uv run pytest

tests/test_stdio.py starts the real server over stdio and calls it through an MCP client, the same way Claude Code does.

Roadmap

• Read Soda and Great Expectations results alongside dbt's.

• OpenMetadata lineage and ownership, so an investigation can name who owns the broken table.

• Snowflake and BigQuery through DuckDB community extensions.

• Distribution checks: a numeric column whose mean or spread shifted between windows.

Contributions are welcome. New checks go in src/dqsleuth/engine.py with a planted fault in examples/make_demo.py and a test that finds it.

License

MIT