Project 3: Production-Grade MCP Server (DuckDB Analytics)

Repository: https://github.com/pypi-ahmad/duckdb-analytics-mcp

Project 3: Production-Grade MCP Server (DuckDB Analytics)

Simple but production-ready MCP server with secure read-only analytics tools over local CSV/JSON/Parquet data.

• Server: duckdb_analytics_mcp
• Transports: stdio, streamable-http
• Python: 3.12.10
• Env manager: uv

Why this is resume-worthy

• Real MCP server using official Python MCP SDK (FastMCP).
• Hardened query path: read-only SQL guardrails, pagination, timeout limits, extension lockdown.
• Deployable with Docker + CI + typed/tested service layer.

Tools and resources

Tools:

1. duckdb_analytics_health
2. duckdb_analytics_list_datasets
3. duckdb_analytics_describe_dataset
4. duckdb_analytics_query_dataset

Resources:

• dataset://catalog
• dataset://schema/{dataset_name}

Setup

git clone https://github.com/pypi-ahmad/duckdb-analytics-mcp.git
cd duckdb-analytics-mcp
uv python pin 3.12.10
uv sync --dev
cp .env.example .env

Run

Streamable HTTP:

uv run duckdb-analytics-mcp run --transport streamable-http

stdio:

uv run duckdb-analytics-mcp run --transport stdio

Doctor check:

uv run duckdb-analytics-mcp doctor

Notebook-first tutorial

uv run python scripts/execute_notebooks.py

Notebook:

1. notebooks/01_mcp_server_tutorial.ipynb

Real validation outputs (executed on June 12, 2026)

Doctor output:

{
  "health": {
    "status": "ok",
    "server": "duckdb_analytics_mcp",
    "dataset_dir": "/home/ahmad/AI/Projects/duckdb-analytics-mcp/data",
    "dataset_count": 2,
    "checked_at": "2026-06-12T11:44:53.075690Z"
  },
  "dataset_preview_count": 2,
  "dataset_total": 2
}

Revenue query output (sales_orders.csv):

{
  "dataset": "sales_orders.csv",
  "total_count": 4,
  "rows": [
    {"region": "North", "revenue": 24646.93},
    {"region": "West", "revenue": 23259.54},
    {"region": "South", "revenue": 18548.94},
    {"region": "East", "revenue": 14552.55}
  ]
}

Quality checks

uv run ruff check .
uv run mypy src
uv run pytest

Latest status:

• ruff: pass
• mypy: pass
• pytest: pass (10 passed)

Docker

docker build -t duckdb-analytics-mcp:latest .
docker run --rm -p 8000:8000 \
  -e HOST=0.0.0.0 \
  -e PORT=8000 \
  -e TRANSPORT=streamable-http \
  duckdb-analytics-mcp:latest