LLM-Based Analytics System with MCP Integration

An MCP server that gives the language model a set of tools for analyzing tabular data: loading, cleaning, plotting, and report assembly. No custom chat interface is developed — the web interface of a ready-made platform is used (Claude as the primary client, ChatGPT as an alternative).

The same tool registry is published over two protocols at once:

What the system can do

12 tools, 5 skills. The full list — by calling describe_system or in ARCHITECTURE.md.

Additional capabilities:

1. Auto-selected analysis — suggest_analysis determines which column is the time axis, which are metrics, which are breakdowns, and returns a ready-made call plan with a justification for each step.

2. Multi-format and multi-source — CSV, TSV, Excel, JSON, Parquet; a catalog, a local path, or an HTTP(S) link. The latter is essential for the web scenario: a file uploaded to a browser chat is unavailable to the server.

3. One-command report assembly — build_report builds the missing charts itself and produces the document in three formats.

Related MCP server: Claude Data Buddy

Installation

Requires Python 3.10 or newer.

git clone <адрес-репозитория>
cd llm-analytics-mcp

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

pip install -r requirements.txt

Step 1. Test data

The data in the repository is synthetically generated according to the Superstore schema. The spec explicitly allows this: "you can generate the data yourself or use a well-known dataset."

python scripts/prepare_dataset.py --synthetic --rows 4000

The ready-made files are already in data/ — the command is needed only if you want to regenerate them or change the volume.

Why synthetic data instead of Kaggle

The generator provides control over exactly what the system demonstrates:

• Verifiable patterns are built in — an upward trend, annual seasonality with a peak at the end of the year, and a "discount above 30% → negative profit" relationship. This makes the analysis conclusions meaningful rather than random.

• Defects are introduced intentionally. The real Superstore is almost perfectly clean: without missing values and duplicates, DataCleaningSkill would report "0 rows removed," and there would be nothing to demonstrate cleaning with.

• Reproducibility. A fixed seed=42 — the reviewer gets exactly the same data and the same figures in the report as in the example.

• The repository is self-contained. No Kaggle account is needed to run the project.

Loading the real Superstore is also supported — the column structure matches:

python scripts/prepare_dataset.py --input ~/Downloads/Sample-Superstore.csv

What the script creates

Columns: Date, Product, Region, Sales, Quantity, Profit (from the spec) plus the breakdowns Category, Sub-Category, Segment, Discount, Ship Mode. Period — 2021–2024, 48 months.

The composition of defects is printed at startup and is deterministic:

Step 2. Verification without a server

An end-to-end run of the entire chain — from loading to a PDF report:

PYTHONPATH=src python -m analytics_mcp.selfcheck

The script repeats what the LLM does in a dialogue, but deterministically. It is useful as a smoke test before a demo: if it passes, the problem is almost certainly in the integration, not in the analytics.

Step 3. Starting the server

PYTHONPATH=src uvicorn analytics_mcp.app:app --host 127.0.0.1 --port 8000

Verification:

curl http://127.0.0.1:8000/health

Useful addresses:

If the port is busy. A previously started process may continue responding with old code — the symptom is deceptive: /health responds, but changes are not applied. Before restarting: pkill -f uvicorn.

Step 4. Public address via ngrok

Claude accesses the server from outside, so an HTTPS address is needed.

# 1. Установка и регистрация: https://ngrok.com/download
ngrok config add-authtoken <ваш-токен>

# 2. В личном кабинете ngrok зарезервируйте бесплатный статический домен
#    (Domains -> Create Domain). Без него адрес меняется при каждом
#    перезапуске, и настройку коннектора придётся повторять.

# 3. Запуск туннеля
ngrok http 8000 --domain=ваш-домен.ngrok-free.app

Then set the address in the environment and restart the server:

cp .env.example .env
# в .env укажите:
#   PUBLIC_BASE_URL=https://ваш-домен.ngrok-free.app

export PUBLIC_BASE_URL=https://ваш-домен.ngrok-free.app
export MCP_ALLOWED_HOSTS='127.0.0.1:*,localhost:*,*.ngrok-free.app'
PYTHONPATH=src uvicorn analytics_mcp.app:app --host 127.0.0.1 --port 8000

The most common "can't connect" cause. The MCP SDK by default enables DNS rebinding protection and accepts only a Host header of the form localhost. Behind a tunnel, Host contains the ngrok domain, and the request is rejected at the connector connection stage, without a clear error in the interface. The MCP_ALLOWED_HOSTS variable solves exactly this problem.

Step 5. Connecting to Claude (primary scenario)

1. Open Settings → Connectors → Add custom connector.

2. Specify the address: https://your-domain.ngrok-free.app/mcp (note the /mcp suffix).

3. Save and make sure the connector transitions to the connected state.

4. In a new dialogue, enable the analytics_mcp connector via the tools menu.

5. Copy the contents of prompts/system_prompt.md into the project description (Project instructions) — this sets the call order.

Verification request: "What datasets are available?" — the model should call list_datasets and show the contents of the catalog.

Step 6. Connecting to ChatGPT (alternative scenario)

1. Download the specification from the public address:

   PUBLIC_BASE_URL=https://ваш-домен.ngrok-free.app \
     PYTHONPATH=src python scripts/export_openapi.py

2. Create a Custom GPT: Explore GPTs → Create → Configure.

3. Create new action → Schema — paste the contents of openapi.json.

4. Authentication: None.

5. In the Instructions field, paste prompts/system_prompt.md.

Details and specifics of chart rendering — in prompts/gpt_action_setup.md.

Demonstration scenario

The order of requests is chosen so that the screenshots show a chain of calls, not a single request. The key frame is step 4: it shows what the model plans, not hardcoded logic.

Example result — docs/report_example.md, charts — in docs/plots/.

Work screenshots

Demo materials are in docs/screenshots/:

The screenshots show the key property of the system: the chain of calls is controlled by the LLM. The model itself decides which tools to call, finds the limitations of the set (for example, the absence of row filtering), and reports them instead of forcing the output to fit.

Integration verification

# Полный цикл по обоим транспортам: initialize, tools/list, tools/call,
# возврат изображения, обработка ошибочных аргументов
python scripts/integration_test.py

Repository structure

llm-analytics-mcp/
├── README.md                    инструкция (этот файл)
├── ARCHITECTURE.md              архитектура и роль MCP/скиллов
├── openapi.json                 спецификация для Custom GPT Action
├── requirements.txt
├── .env.example
├── data/                        тестовые данные
├── docs/
│   ├── report_example.md/html/pdf   пример сгенерированного отчёта
│   ├── plots/                       примеры графиков
│   └── screenshots/                 скриншоты диалога
├── prompts/
│   ├── system_prompt.md         инструкция для LLM
│   └── gpt_action_setup.md      настройка Custom GPT Action
├── scripts/
│   ├── prepare_dataset.py       подготовка данных
│   ├── export_openapi.py        выгрузка спецификации
│   └── integration_test.py      проверка обоих транспортов
└── src/analytics_mcp/
    ├── core/                    реестр инструментов, хранилище, модели
    ├── skills/                  бизнес-логика этапов анализа
    ├── tools/                   инструменты, публикуемые наружу
    ├── transports/              адаптеры MCP и REST
    ├── rendering/               оформление графиков, артефакты
    ├── app.py                   сборка ASGI-приложения
    └── selfcheck.py             сквозная самопроверка

How to add your own tool

The core does not change. Create a file src/analytics_mcp/tools/my_tools.py:

from __future__ import annotations

from analytics_mcp.core.datasets import store
from analytics_mcp.core.registry import tool


@tool(tags=("stats",), skill="DataLoadingSkill", title="Топ значений")
def top_values(column: str, dataset_id: str | None = None, limit: int = 10) -> dict:
    """Возвращает самые частые значения колонки.

    Args:
        column: Имя колонки.
        dataset_id: Датасет. По умолчанию — последний использованный.
        limit: Сколько значений вернуть.
    """
    record = store.get(dataset_id)
    record.require_column(column)
    counts = record.df[column].value_counts().head(limit)
    return {str(k): int(v) for k, v in counts.items()}

Restart the server. The tool will appear immediately in both protocols: in tools/list for MCP and in /openapi.json for REST. The tools package imports its modules automatically, the JSON schema is derived from the signature, and the description — from the docstring.

Known limitations

They are named deliberately — these are the boundaries of the prototype, not unfinished work:

• In-memory dataset storage. When the server restarts, loaded data is lost. Acceptable for a prototype; in production — Redis or disk.

• No authorization. Demo environment is behind a temporary tunnel. For production — an API key in the header and validation on the FastAPI side.

• No row filtering. Tools work with the dataset as a whole: you cannot build a slice like “only the West region for 2024”. This is noticeable in the demo — the model honestly reports what it cannot compute, instead of fudging the output.

• Five skills, not more. A deliberate choice: better five working skills than ten formal ones.

• No unit tests — only the end-to-end self-check selfcheck.py and an integration test of both transports.