Skip to content
Back to search

data-quality-mcp

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/satkynovilgiz--data-quality-mcp/badge.svg)](/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
  1. # data-quality-mcp
  2. An MCP (Model Context Protocol) server that lets an AI client such as Claude inspect CSV datasets and report on their data quality.
  3. 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.
  4. ## Architecture
  5. ```mermaid
  6. flowchart LR
  7. C["MCP client<br/>(Claude Desktop, Claude Code, Inspector)"] -- "JSON-RPC over stdio" --> S
  8. subgraph S["data-quality-mcp"]
  9. direction TB
  10. SV["server.py<br/>FastMCP: tools, resource, prompt"]
  11. SEC["security.py<br/>path validation, size limit, raw CSV read"]
  12. P["profiling.py<br/>type inference, column profiles"]
  13. I["issues.py<br/>detectors"]
  14. SC["scoring.py<br/>0-100 score"]
  15. CL["cleaning.py<br/>ordered suggestions"]
  16. SV --> SEC
  17. SV --> P & I & SC & CL
  18. SC --> I
  19. CL --> I
  20. I --> P
  21. end
  22. SEC -- "read-only" --> D[("DATA_DIR/*.csv")]
  23. ```
  24. `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.
  25. ## Tools
  26. | Tool | Arguments | Returns |
  27. |---|---|---|
  28. | `list_datasets` | – | CSV files in `DATA_DIR` with size and row count (unsafe or oversized files are listed as unreadable) |
  29. | `profile_dataset` | `name` | Rows, columns, and per column: inferred type, missing %, unique count, example values, numeric stats |
  30. | `find_issues` | `name` | Issues with `type`, `severity` (high/medium/low), `column`, `message` and `details` |
  31. | `quality_score` | `name` | 0–100 score, letter grade, breakdown (completeness, uniqueness, validity, consistency), one-line explanation |
  32. | `preview_rows` | `name`, `n=5` | First `n` rows exactly as stored (capped at 20) |
  33. | `suggest_cleaning` | `name` | Ordered cleaning steps with reasons and pandas code. Suggestions only, nothing is modified |
  34. | Resource | Returns |
  35. |---|---|
  36. | `dataset://{name}/schema` | JSON with column names and inferred types |
  37. | Prompt | Does |
  38. |---|---|
  39. | `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 |
  40. All tools carry the MCP `readOnlyHint` annotation.
  41. ### What `find_issues` detects
  42. | Issue type | Rule | Severity |
  43. |---|---|---|
  44. | `disguised_missing` | Placeholders such as `unknown`, `N/A`, `null`, `?`, `-`, or whitespace-only cells | medium if ≥ 5% of rows, else low |
  45. | `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 |
  46. | `high_missing` | > 30% of a column is blank or placeholder | high |
  47. | `constant_column` | Only one distinct non-missing value | medium |
  48. | `duplicate_rows` | Exact duplicate rows (count, %, example row indices) | high if > 5%, else medium |
  49. | `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 |
  50. | `numbers_stored_as_text` | ≥ 90% of values are numbers (incl. `1,200`, `$5`, `42 yrs`) but some are not plain numbers | medium |
  51. ### How `quality_score` works
  52. ```
  53. score = 0.30·completeness + 0.20·uniqueness + 0.30·validity + 0.20·consistency
  54. ```
  55. - **Completeness** is the average of the share of present cells and the share of rows with no missing cell.
  56. - **Uniqueness** is the share of rows that are not exact duplicates.
  57. - **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.
  58. - **Consistency** is the share of columns with no constant value, no IQR outliers and no numbers stored as text.
  59. - **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.
  60. ## Setup
  61. Requires Python 3.11+.
  62. **With uv**
  63. ```bash
  64. git clone <your-repo-url> data-quality-mcp && cd data-quality-mcp
  65. uv venv && uv pip install -e ".[dev]"
  66. uv run data-quality-mcp # starts the server on stdio (Ctrl+C to stop)
  67. ```
  68. **With pip**
  69. ```bash
  70. python3 -m venv .venv && source .venv/bin/activate
  71. pip install -e ".[dev]"
  72. data-quality-mcp
  73. ```
  74. The server reads CSVs from `DATA_DIR` (default `./data`, relative to the working directory). Sample data is included. To regenerate it:
  75. ```bash
  76. python scripts/make_sample_data.py # writes data/customers_clean.csv and data/customers_messy.csv
  77. ```
  78. **Run the checks**
  79. ```bash
  80. ruff check . && ruff format --check .
  81. pytest
  82. ```
  83. ## Try it with MCP Inspector
  84. [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a browser UI for calling a server's tools by hand (needs Node.js):
  85. ```bash
  86. npx @modelcontextprotocol/inspector -e DATA_DIR="$PWD/data" .venv/bin/data-quality-mcp
  87. ```
  88. Open the URL it prints, click **Connect**, then:
  89. 1. **Tools → list_datasets → Run** to see the two sample files.
  90. 2. **quality_score** with `name = customers_messy.csv` returns 85.0; `customers_clean.csv` returns 100.0.
  91. 3. **profile_dataset** with `name = ../pyproject.toml` returns a clear "Access denied" error.
  92. 4. **Resources** tab: `dataset://customers_messy.csv/schema`. **Prompts** tab: `audit_dataset`.
  93. ## Connect to Claude Desktop
  94. 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.
  95. ```json
  96. {
  97. "mcpServers": {
  98. "data-quality": {
  99. "command": "/Users/you/projects/data-quality-mcp/.venv/bin/data-quality-mcp",
  100. "env": {
  101. "DATA_DIR": "/Users/you/projects/data-quality-mcp/data"
  102. }
  103. }
  104. }
  105. }
  106. ```
  107. 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.
  108. ## Connect to Claude Code
  109. ```bash
  110. claude mcp add data-quality \
  111. --env DATA_DIR="$PWD/data" \
  112. -- "$PWD/.venv/bin/data-quality-mcp"
  113. ```
  114. Check it with `claude mcp list`, or `/mcp` inside a session. Add `--scope project` to share the config with your team through `.mcp.json`.
  115. ## Example conversation
  116. > **You:** Is customers_messy.csv ready for training?
  117. Claude calls the three tools (or you run the `audit_dataset` prompt). Abbreviated, these are what they actually returned:
  118. **`profile_dataset`**: 525 rows, 13 columns. Notable columns:
  119. | column | inferred type | missing % | unique |
  120. |---|---|---|---|
  121. | phone | text | 39.43 | 298 |
  122. | email | text | 8.0 | 460 |
  123. | city | categorical | 5.71 | 8 |
  124. | age | integer | 3.05 | 75 |
  125. | data_source | categorical | 0.0 | 1 |
  126. **`find_issues`**: 10 issues, `{"high": 2, "medium": 6, "low": 2}`
  127. ```
  128. high high_missing phone 39.43% missing (207 blank)
  129. high sentinel_value days_since_last_purchase 999 appears 20 times, far outside the rest
  130. medium duplicate_rows – 25 rows (4.76%) are exact duplicates
  131. medium disguised_missing email 42 cells say 'unknown'
  132. medium disguised_missing city 30 cells: 'N/A', '?', whitespace
  133. medium numbers_stored_as_text age 18 values like '65 yrs'
  134. medium constant_column data_source always 'legacy_crm'
  135. medium outliers annual_income 8 values outside [18,903, 98,807]
  136. low disguised_missing age 16 cells say 'unknown'
  137. low disguised_missing plan 10 cells say '-'
  138. ```
  139. **`quality_score`**: `85.0` (grade B). Completeness 72.6, uniqueness 95.2, validity 96.1, consistency 76.9.
  140. > **Claude:**
  141. > **Ready for ML training?** No. There are two high-severity issues and the score is 85/100.
  142. > **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).
  143. > **Score:** 85.0. The weakest dimension is completeness (72.6): only 261 of 525 rows have no missing value.
  144. > **Fix first:** drop duplicates, turn placeholders and the 999 sentinel into NaN, and convert `age` to numeric. `suggest_cleaning` gives the code.
  145. 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.
  146. ## Security
  147. The server gives an AI model access to your filesystem, so it is locked down by default.
  148. - **One allowed directory.** Only files inside `DATA_DIR` (default `./data`) can be read. Every tool, and the resource, goes through `security.resolve_dataset_path()`.
  149. - **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.
  150. - **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.
  151. - **Absolute paths rejected** (`/etc/passwd`, `C:\...`, `\\server\share`) with a message explaining how to pass a relative name.
  152. - **Only `.csv`.** The extension is checked on both the requested name and the real target, so `report.csv → notes.txt` is refused.
  153. - **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.
  154. - **Read-only.** No code path writes, renames or deletes files. `suggest_cleaning` returns text only. Tools are annotated `readOnlyHint: true`.
  155. - **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.
  156. - **No secrets.** The project needs no API keys or network access. `.gitignore` excludes `.env` and key files.
  157. 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).
  158. ## Design decisions
  159. - **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.
  160. - **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.
  161. - **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.
  162. - **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".
  163. - **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.
  164. - **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.
  165. - **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.
  166. - **`server.py` only does registration.** `build_server(data_dir)` is a factory, so tests point the server at fixture directories without touching environment variables.
  167. - **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.
  168. ## Limitations
  169. - CSV only, UTF-8 only, comma-delimited (pandas defaults); no Excel or Parquet, and no delimiter sniffing.
  170. - The whole file (≤ 50 MB) is loaded into memory for analysis; there is no streaming or sampling.
  171. - Only files directly inside `DATA_DIR` are listed; subdirectories are not scanned.
  172. - 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.
  173. - 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).
  174. - Only exact duplicates are found; near-duplicates (`"Alex Smith"` vs `"alex smith "`) are not.
  175. - No cross-column rules (e.g. `signup_date` after `last_purchase`), no PII detection, and no tracking of quality over time.
  176. - The score weights are fixed and opinionated; they are not configurable per use case.
  177. ## What I'd build next
  178. - **Configurable rules:** per-dataset YAML for expected types, allowed ranges, custom placeholder tokens and score weights.
  179. - **Near-duplicate detection** (normalized strings, fuzzy matching on key columns) and **cross-column checks**.
  180. - **PII detection** (emails, phones, IDs) with a warning before data is used for training.
  181. - **Label and leakage checks** for ML: class imbalance, target leakage, train/test drift between two files.
  182. - **Parquet / Excel support** and chunked reading for files over 50 MB.
  183. - **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.
  184. - **Quality history:** store scores over time and alert when a dataset's quality drops.
  185. ## Project layout
  186. ```
  187. src/data_quality_mcp/
  188. server.py FastMCP app: tool/resource/prompt registration only
  189. security.py path validation, size limit, raw CSV loading
  190. profiling.py type inference, column profiles, schema
  191. issues.py the seven detectors + find_issues
  192. scoring.py 0-100 score and breakdown
  193. cleaning.py ordered cleaning suggestions
  194. scripts/make_sample_data.py seeded synthetic data generator
  195. data/ customers_clean.csv, customers_messy.csv (synthetic)
  196. tests/ unit, security, sample-data and in-process MCP tests
  197. ```
  198. ## License
  199. 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 in

Free to use. If it’s helped, pass it on.