Back to search
data-quality-mcp
MCP serverGitHub
MCP server that lets AI clients inspect CSV datasets: profiling, data-quality issues, a 0–100 quality score, and cleaning suggestions. Read-only and sandboxed.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/satkynovilgiz--data-quality-mcp)HTML
<a href="/listings/satkynovilgiz--data-quality-mcp"><img src="/api/listings/satkynovilgiz--data-quality-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Requires Python 3.11+.
**With uv**
git clone <your-repo-url> data-quality-mcp && cd data-quality-mcp uv venv && uv pip install -e ".[dev]" uv run data-quality-mcp # starts the server on stdio (Ctrl+C to stop)
**With pip**
python3 -m venv .venv && source .venv/bin/activate pip install -e ".[dev]" data-quality-mcp
The server reads CSVs from `DATA_DIR` (default `./data`, relative to the working directory). Sample data is included. To regenerate it:
python scripts/make_sample_data.py # writes data/customers_clean.csv and data/customers_messy.csv
**Run the checks**
ruff check . && ruff format --check . pytest
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 260 lines
- # data-quality-mcp
- An MCP (Model Context Protocol) server that lets an AI client such as Claude inspect CSV datasets and report on their data quality.
- It profiles columns, detects problems like disguised missing values, sentinels, duplicates and outliers, gives a 0–100 quality score, and suggests ordered cleaning steps. It is strictly read-only and confined to one directory.
- ## Architecture
- ```mermaid
- flowchart LR
- C["MCP client<br/>(Claude Desktop, Claude Code, Inspector)"] -- "JSON-RPC over stdio" --> S
- subgraph S["data-quality-mcp"]
- direction TB
- SV["server.py<br/>FastMCP: tools, resource, prompt"]
- SEC["security.py<br/>path validation, size limit, raw CSV read"]
- P["profiling.py<br/>type inference, column profiles"]
- I["issues.py<br/>detectors"]
- SC["scoring.py<br/>0-100 score"]
- CL["cleaning.py<br/>ordered suggestions"]
- SV --> SEC
- SV --> P & I & SC & CL
- SC --> I
- CL --> I
- I --> P
- end
- SEC -- "read-only" --> D[("DATA_DIR/*.csv")]
- ```
- `server.py` only registers things. All analysis lives in pure functions with no MCP imports (`profiling`, `issues`, `scoring`, `cleaning`), so they are easy to unit test. `security.py` is the only module that touches the filesystem.
- ## Tools
- | Tool | Arguments | Returns |
- |---|---|---|
- | `list_datasets` | – | CSV files in `DATA_DIR` with size and row count (unsafe or oversized files are listed as unreadable) |
- | `profile_dataset` | `name` | Rows, columns, and per column: inferred type, missing %, unique count, example values, numeric stats |
- | `find_issues` | `name` | Issues with `type`, `severity` (high/medium/low), `column`, `message` and `details` |
- | `quality_score` | `name` | 0–100 score, letter grade, breakdown (completeness, uniqueness, validity, consistency), one-line explanation |
- | `preview_rows` | `name`, `n=5` | First `n` rows exactly as stored (capped at 20) |
- | `suggest_cleaning` | `name` | Ordered cleaning steps with reasons and pandas code. Suggestions only, nothing is modified |
- | Resource | Returns |
- |---|---|
- | `dataset://{name}/schema` | JSON with column names and inferred types |
- | Prompt | Does |
- |---|---|
- | `audit_dataset(name)` | Asks the model to call `profile_dataset`, `find_issues` and `quality_score`, then write a short "Ready for ML training? yes/no + why" report |
- All tools carry the MCP `readOnlyHint` annotation.
- ### What `find_issues` detects
- | Issue type | Rule | Severity |
- |---|---|---|
- | `disguised_missing` | Placeholders such as `unknown`, `N/A`, `null`, `?`, `-`, or whitespace-only cells | medium if ≥ 5% of rows, else low |
- | `sentinel_value` | `999`, `9999`, `-1`, `-999`… in a numeric column, **only when suspicious**: repeats ≥ 2×, and lies beyond Q1 − 3·IQR / Q3 + 3·IQR of the other values, or is negative while all other values are ≥ 0 | high |
- | `high_missing` | > 30% of a column is blank or placeholder | high |
- | `constant_column` | Only one distinct non-missing value | medium |
- | `duplicate_rows` | Exact duplicate rows (count, %, example row indices) | high if > 5%, else medium |
- | `outliers` | Tukey IQR rule (k = 1.5); returns count and bounds; sentinels are excluded first so they aren't double-counted | medium if ≥ 1%, else low |
- | `numbers_stored_as_text` | ≥ 90% of values are numbers (incl. `1,200`, `$5`, `42 yrs`) but some are not plain numbers | medium |
- ### How `quality_score` works
- ```
- score = 0.30·completeness + 0.20·uniqueness + 0.30·validity + 0.20·consistency
- ```
- - **Completeness** is the average of the share of present cells and the share of rows with no missing cell.
- - **Uniqueness** is the share of rows that are not exact duplicates.
- - **Validity** is the average of the share of present cells matching their column's type (sentinels count as invalid) and the share of rows with no invalid cell.
- - **Consistency** is the share of columns with no constant value, no IQR outliers and no numbers stored as text.
- - **Auto-generated flag columns** (`age_was_missing`, `is_outlier`, `income_imputed`, `Unnamed: 0`…, which need both a flag-like name *and* binary values) are excluded everywhere. They are 100% complete by construction and would otherwise inflate completeness after cleaning.
- ## Setup
- Requires Python 3.11+.
- **With uv**
- ```bash
- git clone <your-repo-url> data-quality-mcp && cd data-quality-mcp
- uv venv && uv pip install -e ".[dev]"
- uv run data-quality-mcp # starts the server on stdio (Ctrl+C to stop)
- ```
- **With pip**
- ```bash
- python3 -m venv .venv && source .venv/bin/activate
- pip install -e ".[dev]"
- data-quality-mcp
- ```
- The server reads CSVs from `DATA_DIR` (default `./data`, relative to the working directory). Sample data is included. To regenerate it:
- ```bash
- python scripts/make_sample_data.py # writes data/customers_clean.csv and data/customers_messy.csv
- ```
- **Run the checks**
- ```bash
- ruff check . && ruff format --check .
- pytest
- ```
- ## Try it with MCP Inspector
- [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a browser UI for calling a server's tools by hand (needs Node.js):
- ```bash
- npx @modelcontextprotocol/inspector -e DATA_DIR="$PWD/data" .venv/bin/data-quality-mcp
- ```
- Open the URL it prints, click **Connect**, then:
- 1. **Tools → list_datasets → Run** to see the two sample files.
- 2. **quality_score** with `name = customers_messy.csv` returns 85.0; `customers_clean.csv` returns 100.0.
- 3. **profile_dataset** with `name = ../pyproject.toml` returns a clear "Access denied" error.
- 4. **Resources** tab: `dataset://customers_messy.csv/schema`. **Prompts** tab: `audit_dataset`.
- ## Connect to Claude Desktop
- Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`, Windows: `%APPDATA%\Claude\claude_desktop_config.json`). Use **absolute paths**: Claude Desktop does not start in your project folder, so `./data` would not resolve to it.
- ```json
- {
- "mcpServers": {
- "data-quality": {
- "command": "/Users/you/projects/data-quality-mcp/.venv/bin/data-quality-mcp",
- "env": {
- "DATA_DIR": "/Users/you/projects/data-quality-mcp/data"
- }
- }
- }
- }
- ```
- Fully quit and restart Claude Desktop. The six tools then appear in the chat's tools/connectors menu, and `audit_dataset` is listed among the server's prompts.
- ## Connect to Claude Code
- ```bash
- claude mcp add data-quality \
- --env DATA_DIR="$PWD/data" \
- -- "$PWD/.venv/bin/data-quality-mcp"
- ```
- Check it with `claude mcp list`, or `/mcp` inside a session. Add `--scope project` to share the config with your team through `.mcp.json`.
- ## Example conversation
- > **You:** Is customers_messy.csv ready for training?
- Claude calls the three tools (or you run the `audit_dataset` prompt). Abbreviated, these are what they actually returned:
- **`profile_dataset`**: 525 rows, 13 columns. Notable columns:
- | column | inferred type | missing % | unique |
- |---|---|---|---|
- | phone | text | 39.43 | 298 |
- | email | text | 8.0 | 460 |
- | city | categorical | 5.71 | 8 |
- | age | integer | 3.05 | 75 |
- | data_source | categorical | 0.0 | 1 |
- **`find_issues`**: 10 issues, `{"high": 2, "medium": 6, "low": 2}`
- ```
- high high_missing phone 39.43% missing (207 blank)
- high sentinel_value days_since_last_purchase 999 appears 20 times, far outside the rest
- medium duplicate_rows – 25 rows (4.76%) are exact duplicates
- medium disguised_missing email 42 cells say 'unknown'
- medium disguised_missing city 30 cells: 'N/A', '?', whitespace
- medium numbers_stored_as_text age 18 values like '65 yrs'
- medium constant_column data_source always 'legacy_crm'
- medium outliers annual_income 8 values outside [18,903, 98,807]
- low disguised_missing age 16 cells say 'unknown'
- low disguised_missing plan 10 cells say '-'
- ```
- **`quality_score`**: `85.0` (grade B). Completeness 72.6, uniqueness 95.2, validity 96.1, consistency 76.9.
- > **Claude:**
- > **Ready for ML training?** No. There are two high-severity issues and the score is 85/100.
- > **Why:** `phone` is 39% empty; `days_since_last_purchase` uses 999 as a "never purchased" code in 20 rows, which would wreck any model of recency; 25 rows (4.8%) are duplicates; `age` mixes numbers with text like "65 yrs" and "unknown"; `annual_income` has 8 extreme values (from -5,000 up to 1.2M).
- > **Score:** 85.0. The weakest dimension is completeness (72.6): only 261 of 525 rows have no missing value.
- > **Fix first:** drop duplicates, turn placeholders and the 999 sentinel into NaN, and convert `age` to numeric. `suggest_cleaning` gives the code.
- Running all 11 suggested steps on a copy raises the score from **85.0 to 96.6** with zero remaining issues. A test (`tests/test_sample_data.py`) checks this.
- ## Security
- The server gives an AI model access to your filesystem, so it is locked down by default.
- - **One allowed directory.** Only files inside `DATA_DIR` (default `./data`) can be read. Every tool, and the resource, goes through `security.resolve_dataset_path()`.
- - **Path traversal blocked.** The requested name is joined to `DATA_DIR` and `resolve()`d, which collapses `..` and follows symlinks. The result must still be inside `DATA_DIR` (`Path.is_relative_to`). So `../../etc/passwd`, `sub/../../secret.csv` and similar names are rejected.
- - **Symlinks can't escape.** Because the check runs on the *resolved* path, a `data/link.csv → /home/me/secret.csv` symlink is rejected. A symlink that stays inside `DATA_DIR` is allowed.
- - **Absolute paths rejected** (`/etc/passwd`, `C:\...`, `\\server\share`) with a message explaining how to pass a relative name.
- - **Only `.csv`.** The extension is checked on both the requested name and the real target, so `report.csv → notes.txt` is refused.
- - **Size and output limits.** Files over **50 MB** are refused before being opened. `preview_rows` returns at most **20 rows** and reads only those rows.
- - **Read-only.** No code path writes, renames or deletes files. `suggest_cleaning` returns text only. Tools are annotated `readOnlyHint: true`.
- - **No crashes on bad input.** Validation failures, malformed CSVs, empty files and non-UTF-8 files raise `DatasetAccessError`, which the client receives as an MCP tool error (`isError: true`) with a readable message. The server keeps running; a test checks this.
- - **No secrets.** The project needs no API keys or network access. `.gitignore` excludes `.env` and key files.
- These checks are covered by `tests/test_security.py` (traversal, absolute paths, escaping symlinks, non-CSV files, missing files, a real 50 MB + 1 byte file) and `tests/test_mcp_server.py` (the same errors through the MCP client).
- ## Design decisions
- - **Read every cell as a raw string** (`dtype=str, keep_default_na=False`). Pandas would otherwise silently turn `"N/A"` into NaN and `"007"` into 7, hiding exactly the problems this tool looks for. Types are inferred afterwards.
- - **Type inference with a 90% threshold.** A column is numeric if ≥ 90% of its non-missing values are plain numbers. That way a numeric column polluted with `"65 yrs"` is still recognized as numeric, and then flagged as *numbers stored as text*, instead of being misclassified as text.
- - **Sentinels must look suspicious.** Flagging every 999 would produce false positives (a $999 price is normal), so a sentinel has to repeat and sit beyond 3×IQR, or be negative in an otherwise non-negative column.
- - **Each problem is reported once.** Sentinels are removed before outlier detection, and placeholders are handled by the disguised-missing detector rather than counted as "text in a numeric column".
- - **Cell- *and* row-level rates in the score.** With cell rates only, a column that is 40% empty is about 3% of a 13-column table, and the messy sample scored an "A" (92.9). Averaging in the row rate (rows that survive `dropna()`) reflects what a model actually sees; messy now scores 85.0 against 100.0 for clean.
- - **Flag columns excluded from scoring.** The cleaning plan suggests adding `phone_was_missing` indicators. Without the exclusion, adding them would inflate completeness. Detection requires a flag-like name *and* binary values, so a real feature like `is_active` is not excluded.
- - **Cleaning order matters.** Dedupe → placeholders to NaN → numeric conversion → sentinels → drop constant/sparse columns → outliers → re-verify. A test executes the generated pandas code and checks the score goes up.
- - **`server.py` only does registration.** `build_server(data_dir)` is a factory, so tests point the server at fixture directories without touching environment variables.
- - **MCP SDK 1.x (`mcp>=1.10,<2`).** The brief asked for FastMCP, which lives at `mcp.server.fastmcp` in SDK 1.x. In SDK 2.x it was renamed `MCPServer` and other APIs changed, so the dependency is pinned below 2.
- ## Limitations
- - CSV only, UTF-8 only, comma-delimited (pandas defaults); no Excel or Parquet, and no delimiter sniffing.
- - The whole file (≤ 50 MB) is loaded into memory for analysis; there is no streaming or sampling.
- - Only files directly inside `DATA_DIR` are listed; subdirectories are not scanned.
- - Dataset names containing `:` are rejected (this blocks Windows drive paths such as `C:x.csv`), so a file literally named `a:b.csv` cannot be read.
- - Heuristics are heuristics. The placeholder list is English-centric, type inference is threshold-based, and IQR assumes roughly unimodal data (skewed columns such as incomes can produce "outliers" that are real).
- - Only exact duplicates are found; near-duplicates (`"Alex Smith"` vs `"alex smith "`) are not.
- - No cross-column rules (e.g. `signup_date` after `last_purchase`), no PII detection, and no tracking of quality over time.
- - The score weights are fixed and opinionated; they are not configurable per use case.
- ## What I'd build next
- - **Configurable rules:** per-dataset YAML for expected types, allowed ranges, custom placeholder tokens and score weights.
- - **Near-duplicate detection** (normalized strings, fuzzy matching on key columns) and **cross-column checks**.
- - **PII detection** (emails, phones, IDs) with a warning before data is used for training.
- - **Label and leakage checks** for ML: class imbalance, target leakage, train/test drift between two files.
- - **Parquet / Excel support** and chunked reading for files over 50 MB.
- - **An opt-in `apply_cleaning` tool** that writes a *new* file to a separate output directory, never overwriting the source, to keep the read-only guarantee for inputs.
- - **Quality history:** store scores over time and alert when a dataset's quality drops.
- ## Project layout
- ```
- src/data_quality_mcp/
- server.py FastMCP app: tool/resource/prompt registration only
- security.py path validation, size limit, raw CSV loading
- profiling.py type inference, column profiles, schema
- issues.py the seven detectors + find_issues
- scoring.py 0-100 score and breakdown
- cleaning.py ordered cleaning suggestions
- scripts/make_sample_data.py seeded synthetic data generator
- data/ customers_clean.csv, customers_messy.csv (synthetic)
- tests/ unit, security, sample-data and in-process MCP tests
- ```
- ## License
- MIT. See [LICENSE](LICENSE). The sample data is synthetic: names come from short generic lists and all emails use the reserved `example.com` domain.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.