mcp-data-summary

A learning project for building an MCP server with the official Python SDK.

The server lets an LLM produce a visual summary report from CSV datasets without ever loading raw data into the model's context. It simulates a REST API (fake GET/POST), exposes data schemas as MCP Resources, provides chart and document generation as MCP Tools, and guides the whole workflow with an MCP Prompt.

What it demonstrates

How it works

The LLM never sees raw tabular data. Instead it follows this pipeline:

GET /datasets                 → discover available datasets
GET /datasets/{name}          → inspect a plot-friendly schema (columns, dtypes, sample values)
tool: get_summary_statistics  → understand distributions and correlations
tool: generate_*_chart        → produce PNG charts saved to output/ and feedbacks to understand the charts
tool: build_html_report       → render a Jinja2 HTML report from the chart paths
tool: export_pdf_report       → convert HTML to PDF and POST it back to the fake API

Project structure

mcp-data-summary/
├── data/                              # Sample CSV files and JSON dataset descriptions (auto-discovered)
│   ├── descriptions.json
│   ├── sales.csv
│   └── users.csv
├── output/                            # Generated charts, HTML and PDF reports
├── scripts/
│   └── run_pipeline.py                # End-to-end pipeline runner (no LLM needed)
├── tests/
│   ├── conftest.py                    # Shared pytest fixtures
│   ├── test_fake_client.py            # Unit tests for the API layer
│   ├── test_chart_tools.py            # Tests for all chart tools
│   └── test_stats_and_docs.py         # Tests for stats tool + HTML builder
├── src/
│   └── mcp_data_summary/
│       ├── server.py                  # Entry point — wires everything together
│       ├── api/
│       │   ├── fake_client.py         # Simulates GET /datasets and POST /reports
|       |   ├── json_encoder.py        # Custom JSON encoder
│       │   └── schemas.py             # Pydantic models for API responses
│       ├── resources/
│       │   └── datasets.py            # MCP Resources: dataset list + schema
│       ├── tools/
│       │   ├── chart_tools.py         # Bar, line, histogram, pie chart tools
│       │   ├── stats_tools.py         # Summary statistics + scatter plot
│       │   └── document_tools.py      # HTML report builder + PDF exporter
│       └── prompts/
│           └── summary_prompt.py      # Guided 7-step workflow prompt
└── pyproject.toml

Quick start

1. Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install dependencies

uv sync

3. Verify everything works (no LLM required)

Run the pipeline script — it simulates the full LLM workflow end-to-end:

uv run python scripts/run_pipeline.py

# Restrict to a single dataset
uv run python scripts/run_pipeline.py --datasets sales

Charts and a report will appear in output/.

4. Run the test suite

uv run pytest

5. Open the MCP Inspector (browser-based debug UI)

uv run mcp dev src/mcp_data_summary/server.py

This lets you browse Resources, call Tools manually, and inspect request/response payloads

6. Example - Connect to Claude Desktop

Add this block to your claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows):

{
  "mcpServers": {
    "data-summary": {
      "command": "uv",
      "args": [
        "--directory", "/absolute/path/to/mcp-data-summary",
        "run", "mcp-data-summary"
      ]
    }
  }
}

Restart Claude Desktop, then load the data_summary_workflow prompt. The LLM will discover datasets, inspect schemas, generate charts, and produce a PDF report autonomously.

Available tools

Available resources

Adding your own CSV

Drop any .csv file into data/. The server auto-discovers it on startup. Add a description in data/descriptions.json:

{
    "your_file": "Description the LLM will see when reading the schema.",
}

Date columns are auto-detected if their name contains "date".

System dependencies for PDF export

WeasyPrint (used by export_pdf_report) requires Cairo and Pango to be installed at the OS level. The HTML report and all charts work without them.

# Ubuntu / Debian
sudo apt install libpango-1.0-0 libcairo2 libpangocairo-1.0-0

# macOS
brew install pango cairo

# Windows — follow the WeasyPrint install guide:
# https://doc.courtbouillon.org/weasyprint/stable/first_steps.html

Next steps

• Support multi-dataset joins before charting
• Introduce a simple auth token to the fake API layer
• Stream chart generation progress back to the client using MCP notifications