DataLens MCP
by Alaina1713
README.md
# DataLens MCP
**A lightweight Model Context Protocol (MCP) server for data exploration and quality checks.**
DataLens gives AI assistants a practical way to inspect local datasets, understand their structure, identify common data-quality issues, and run read-only analytical SQL — without manually opening a notebook.
## Why this project?
Data work often starts with repetitive questions:
- What datasets are available?
- How many rows and columns does this file contain?
- Which columns have missing values?
- Are there duplicate records?
- Can I quickly aggregate or filter the data?
DataLens exposes these workflows as MCP tools so an MCP-compatible client can call them directly.
## Features
| MCP tool | What it does |
|---|---|
| `list_datasets` | Finds supported files and reports their format and size |
| `describe_dataset` | Returns row count, column names, and inferred types |
| `profile_dataset` | Reports null percentages, distinct counts, and sample values |
| `detect_quality_issues` | Flags missing values and duplicate-row groups |
| `run_sql` | Executes capped, read-only SQL against a selected dataset |
Also includes a small `datalens://about` resource.
**Supported inputs:** CSV and Parquet for querying. SQLite files are listed for discovery but are not yet queryable through the current flat-dataset tools.
## Quick start
### 1. Clone and install
```bash
git clone https://github.com/YOUR_USERNAME/datalens-mcp.git
cd datalens-mcp
python -m venv .venv
# macOS/Linux
source .venv/bin/activate
# Windows PowerShell
# .venv\Scripts\Activate.ps1
pip install -e ".[dev]"
```
### 2. Add a dataset
Create a `data/` directory and copy a CSV or Parquet file into it:
```bash
mkdir data
cp examples/employees.csv data/employees.csv
```
Or point DataLens to another folder:
```bash
# macOS/Linux
export DATALENS_DATA_DIR="/absolute/path/to/your/data"
# Windows PowerShell
$env:DATALENS_DATA_DIR = "C:\path\to\your\data"
```
### 3. Run the MCP server
```bash
datalens-mcp
```
The server uses **stdio transport**, which is the standard local MCP setup for desktop clients.
## Example MCP client configuration
For an MCP client that supports local stdio servers, use a configuration similar to:
```json
{
"mcpServers": {
"datalens": {
"command": "python",
"args": ["-m", "datalens_mcp.server"],
"env": {
"DATALENS_DATA_DIR": "/absolute/path/to/datalens-mcp/data"
}
}
}
}
```
If your client launches the installed console script instead, use `datalens-mcp` as the command.
## Example prompts
Once connected, try asking your assistant:
- "What datasets can you access?"
- "Profile the employees dataset and explain the columns."
- "Find missing values and duplicate records in employees."
- "Show average salary by department."
- "Which department has the highest average salary?"
Example SQL for `run_sql`:
```sql
SELECT department, ROUND(AVG(salary), 2) AS average_salary
FROM employees
GROUP BY department
ORDER BY average_salary DESC
```
## Design and safety notes
- SQL is restricted to a single `SELECT` or `WITH` statement.
- Mutating and administrative SQL keywords are rejected.
- Query results are capped (maximum 500 rows).
- Dataset names and column identifiers are validated before being interpolated into SQL.
- Only files directly inside the configured data directory are discovered.
- Treat datasets as trusted local inputs. This is a developer utility, not a hardened multi-tenant data service.
The SQL guard is a useful safety layer, not a substitute for operating-system sandboxing. Do not expose this local server to untrusted users or place sensitive files in its data directory.
## Run tests
```bash
pytest
```
## Roadmap
- [ ] SQLite table discovery and querying
- [ ] Parquet partition and large-file profiling optimizations
- [ ] Configurable quality rules (uniqueness, ranges, regex, freshness)
- [ ] Exportable Markdown/JSON profiling reports
- [ ] Optional semantic descriptions for columns
- [ ] More granular per-dataset access controls
## Tech stack
- Python
- Model Context Protocol (MCP) Python SDK
- DuckDB
## Author
**Alaina Rahim**
MSc Advanced Computer Science (Artificial Intelligence), University of Leeds
---
If you build on DataLens, feel free to open an issue or submit a pull request.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues