Provides tools for inspecting and analyzing DuckDB databases, including auto-discovery of tables and columns, data quality checks, and generating natural-language RCA reports.
Integrates with locally-run Ollama models to generate plain-English Root Cause Analysis reports based on data quality checks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@database-mcp run quality check on the orders table"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A generic MCP server that connects to a DuckDB database, auto-inspects the schema, runs data quality checks across every table and column, and uses a local Ollama LLM to generate a natural-language Root Cause Analysis (RCA) report.
No table names or column names are ever hardcoded. Everything is discovered at runtime from the connection config alone.
Auto-discovery — pass connection details, the server lists all tables; pick one and it figures out every column and type
Type-aware checks — numeric columns get distribution stats + Z-score thresholds; VARCHAR columns get cardinality + top values; TIMESTAMP columns get gap detection
Ollama ReAct loop — llama3.2 (default) iteratively calls tools to drill down, then writes a plain-English RCA report
MCP tools — usable directly from any MCP client (Claude, etc.)
REST API — thin FastAPI layer for programmatic access
Related MCP server: dbt-doctor
Layer | Tool |
MCP framework | FastMCP |
Database | DuckDB |
LLM | Ollama ( |
REST API | FastAPI + Uvicorn |
Tests | Plain Python scripts ( |
git clone https://github.com/hargurjeet/database-mcp.git
cd database-mcp
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .envOllama must be running locally:
ollama pull llama3.2
ollama serveEdit .env:
OLLAMA_MODEL=llama3.2 # or mistral:7b
OLLAMA_BASE_URL=http://localhost:11434
REPORTS_PATH=./data/reports/python mcp_server/server.pyAvailable tools:
Tool | What it does |
| Lists all tables — call this first |
| Columns + types for a table |
| Null % per column |
| Total row count |
| Mean / std / min / max for a numeric column |
| Distinct count + top values for a VARCHAR column |
| Gap analysis for a TIMESTAMP column |
| Runs all applicable checks — returns full summary |
All tools accept a config_json string:
{"db_type": "duckdb", "db_path": "./data/warehouse.db", "table": "trips"}table is only required for table-specific tools. tool_list_tables needs only the connection fields.
uvicorn api.main:app --reload
# Swagger UI at http://localhost:8000/docsMethod | Endpoint | Body / Params | What it does |
|
|
| List all tables |
|
|
| Full quality check, returns JSON |
|
|
| Full check + Ollama RCA, saves Markdown report |
|
| — | Retrieve last saved RCA report |
Example:
# List tables
curl "http://localhost:8000/tables?db_path=./data/warehouse.db"
# Run full quality check
curl -X POST http://localhost:8000/check/trips \
-H "Content-Type: application/json" \
-d '{"db_type":"duckdb","db_path":"./data/warehouse.db"}'
# Generate RCA report (requires Ollama)
curl -X POST http://localhost:8000/rca/trips \
-H "Content-Type: application/json" \
-d '{"db_type":"duckdb","db_path":"./data/warehouse.db"}'python agent/dispatcher.py '{
"db_type": "duckdb",
"db_path": "./data/warehouse.db",
"table": "trips"
}'Report is printed to stdout and saved to data/reports/trips_rca.md.
python tests/test_null_tools.py
python tests/test_schema_tools.py
python tests/test_distribution_tools.py
python tests/test_volume_tools.py
python tests/test_cardinality_tools.py
python tests/test_timestamp_tools.py
python tests/test_api.py23 tests total. All use in-memory DuckDB — no external dependencies required.
database-mcp/
├── api/
│ ├── main.py # FastAPI app
│ └── routes.py # Route handlers
│
├── mcp_server/
│ ├── server.py # FastMCP entrypoint + tool registration
│ ├── introspector.py # Schema → check plan mapping
│ ├── connectors/
│ │ ├── base.py # Abstract connector interface
│ │ └── duckdb_connector.py
│ └── tools/
│ ├── schema_tools.py
│ ├── null_tools.py
│ ├── volume_tools.py
│ ├── distribution_tools.py
│ ├── cardinality_tools.py
│ └── timestamp_tools.py
│
├── agent/
│ ├── dispatcher.py # Ollama ReAct loop
│ ├── ollama_client.py
│ └── prompts.py
│
├── data/reports/ # Saved RCA reports
├── docs/session_log.md # Full development history
└── tests/Phase | Status |
Phase 1 — DuckDB + core tools + Ollama loop | Complete |
Phase 2 — PostgreSQL / MySQL connectors | Skipped |
Phase 3 — Prefect scheduled scans | Skipped |
Phase 4 — REST API | Complete |
This server cannot be deployed
Auto-discover validation rules from data — scan, profile, health-score. No rules to write.
The grounded data layer for any LLM: governed SQL, metrics, lineage and catalog over your data.
Deterministic validation for AI-generated artifacts: JSON Schema, OpenAPI response, SQL syntax.
Query PostgreSQL databases in plain English — LLM-generated, safety-validated SQL.
