DataSearcher MCP

Подключи базу данных к Claude или Cursor — и спрашивай на русском: «какие товары продаются хуже всего», «найди аномалии в продажах», «прогноз на 3 месяца». 36 инструментов анализа работают за кулисами: SQL, статистика, ML, графики, дашборды.

---

Что это такое?

DataSearcher MCP — это мост между вашей базой данных и ИИ-ассистентом (Claude Desktop, Cursor, VS Code).

Обычно, чтобы проанализировать данные из БД, нужно писать SQL-запросы вручную или открывать BI-систему. С этим MCP-сервером вы просто разговариваете с ИИ на обычном русском языке, а он сам:

• пишет и выполняет SQL к вашей базе
• строит графики и дашборды
• находит аномалии, корреляции, инсайты
• прогнозирует тренды (ML)
• генерирует HTML-отчёты

Пример диалога

Вы: Подключись к моей PostgreSQL и покажи топ-5 регионов по выручке

ИИ: [вызывает sql_query → SQL выполняется прямо в вашей PostgreSQL]
    Вот топ-5 регионов по выручке:
    | Регион       | Выручка     | Заказов |
    |--------------|-------------|---------|
    | Москва       | 1 358 468 ₽ | 55      |
    | Новосибирск  | 1 036 564 ₽ | 45      |
    ...

Вы: Найди аномалии в суммах заказов

ИИ: [вызывает detect_anomalies → z-score + IQR]
    Обнаружено 3 выброса в колонке amount:
    - Заказ #1047: 49 870 ₽ (z-score = 4.2)
    - Заказ #2891: 48 200 ₽ (z-score = 3.8)
    ...

Вы: Построй дашборд и сохрани как HTML

ИИ: [вызывает create_public_dashboard → генерирует HTML с графиками и фильтрами]
    Дашборд создан! Откройте файл:
    /tmp/datasearcher_mcp_dashboards/abc123/dashboard.html

Почему это круто?

Без DataSearcher MCP	С DataSearcher MCP
Пишешь SQL вручную	ИИ сам пишет и выполняет SQL
Открываешь BI-систему для графиков	Графики и дашборды прямо в чате
Excel для сводных таблиц	pivot_table одним вызовом
Python + Jupyter для ML	Прогнозы и кластеризация через чат
Каждая БД — свой диалект SQL	Пишешь на DuckDB SQL — сервер переводит

---

Чем отличается от других MCP-серверов?

1. SQL выполняется в вашей базе, а не во встроенной

Большинство аналитических инструментов выгружают данные в свой движок. Мы — нет.

Когда вы спрашиваете «покажи продажи по регионам», SQL выполняется напрямую в вашей PostgreSQL/MySQL/ClickHouse — с индексами, оптимизатором, кешем. Никакой выгрузки 50 000 строк в память.

DuckDB подключается только для ML-задач (кластеризация, прогнозы, важность признаков), где он реально нужен. И даже тогда — выгружает не всю таблицу, а только нужные колонки.

Почему так? Ваша production-БД умнее любого встроенного движка. У неё есть индексы, оптимизатор, материализованные представления. Нет смысла выгружать данные, чтобы посчитать GROUP BY.

2. Пишешь на одном SQL — работает в любой БД

Написали DATE_TRUNC('month', date_col) (DuckDB-синтаксис)? Сервер автоматически переведёт это в:

• DATE_TRUNC('MONTH', date_col) для PostgreSQL
• DATE_FORMAT(date_col, '%Y-%m-01') для MySQL
• toStartOfMonth(date_col) для ClickHouse

Трансляция через sqlglot — вам не нужно помнить диалекты.

3. Кросс-БД JOIN через federated-режим

Можно прицепить PostgreSQL и MySQL к DuckDB одновременно и сделать JOIN между ними:

SELECT pg.users.name, mysql.orders.amount
FROM pg.users JOIN mysql.orders ON pg.users.id = mysql.orders.user_id

Это работает через DuckDB extensions (postgres_scanner, mysql_scanner) — без выгрузки данных.

4. Авто-определение связей между таблицами

Сервер читает внешние ключи из information_schema и сам предлагает, как соединить таблицы. Вызов merge_tables без указания ключей — найдёт их автоматически:

Вы: Объедини таблицы orders и customers
ИИ: [merge_tables → авто-найден ключ customer_id → id]
    Объединено: 100 заказов + 20 клиентов → 100 строк

5. Семантический поиск по текстовым данным

Инструмент semantic_search находит строки, похожие по смыслу, а не по словам:

Вы: Найди отзывы, похожие на "доставка задерживается"
ИИ: [semantic_search → LLM embeddings → cosine similarity]
    Топ-3 похожих отзыва:
    1. "Курьер приехал на два часа позже" (similarity: 0.92)
    2. "Ждали посылку 5 дней вместо двух" (similarity: 0.88)
    3. "Срок доставки перенесли без уведомления" (similarity: 0.85)

---

Быстрый старт

Шаг 1. Установка

git clone https://github.com/MarkIvor/mcp-datasearcher.git
cd mcp-datasearcher
pip install -e ".[all]"    # все драйверы БД

Шаг 2. Настройка подключений

cp connections.example.yaml connections.yaml

Отредактируйте connections.yaml — укажите свою БД:

connections:
  - name: my_db
    db_type: postgresql          # postgresql | mysql | clickhouse | sqlite
    host: localhost
    port: 5432
    database: mydb
    username: ${DB_USER}         # подстановка из переменных окружения
    password: ${DB_PASSWORD}
    mode: auto                   # auto (по умолчанию) | remote | dump

# Файлы тоже можно (грузятся в DuckDB):
# files:
#   - path: ./data/sales.csv
#     table_name: sales
#   - path: ./data/report.xlsx
#     table_name: report          # все листы → отдельные таблицы

Шаг 3. Подключение к Claude Desktop

Добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "datasearcher": {
      "command": "datasearcher-mcp",
      "args": ["--config", "/path/to/connections.yaml"]
    }
  }
}

Перезапустите Claude Desktop. Готово! Теперь можно спрашивать:

• «расскажи о данных в таблице orders»
• «найди корреляции между числовыми колонками»
• «построй прогноз продаж на 6 месяцев»
• «создай дашборд по клиентам»

Альтернативы: Cursor, Docker, HTTP

<details> <summary><b>Cursor</b> — конфигурация</summary>

.cursor/mcp.json:

{
  "mcpServers": {
    "datasearcher": {
      "command": "datasearcher-mcp",
      "args": ["--config", "/path/to/connections.yaml"]
    }
  }
}

</details>

<details> <summary><b>Docker</b> — для production / удалённого доступа</summary>

# 1. Подготовьте конфиг:
cp connections.example.yaml connections.yaml

# 2. Запустите:
docker compose up -d

# 3. Подключитесь к http://localhost:8000/mcp

Для Claude Desktop через Docker (stdio):

docker run -i --rm -v ./connections.yaml:/app/connections.yaml:ro \
  datasearcher-mcp --transport stdio

Переменные окружения для Docker:

LLM_BASE_URL=http://ollama:11434/v1   # для classify_rows / semantic_search
LLM_MODEL=qwen2.5:14b
MCP_AUTH_TOKEN=your-secret-token       # опционально, для HTTP auth

</details>

<details> <summary><b>HTTP / SSE</b> — удалённый доступ без Docker</summary>

datasearcher-mcp --transport http --host 0.0.0.0 --port 8000

Точка подключения: http://localhost:8000/mcp

Тест через MCP Inspector:

npx -y @modelcontextprotocol/inspector
# В UI подключитесь к http://localhost:8000/mcp

</details>

---

36 инструментов — что умеет

Анализ данных

Инструмент	Что делает	Пример запроса
sql_query	SQL-запрос к БД (markdown/json/csv)	«покажи топ-10 клиентов по выручке»
smart_summary	Умное саммари таблицы	«расскажи о данных»
profile_data	Статистика по колонкам	«профилируй колонку amount»
data_quality_report	Аудит качества (пропуски, дубликаты)	«проверь качество данных»
auto_insights	Топ-5 инсайтов автоматически	«что интересного в данных?»
sample_data	Выборка строк	«покажи 10 случайных строк»
find_duplicates	Дубликаты (точные и fuzzy)	«найди дубликаты клиентов»
detect_anomalies	Выбросы (z-score, IQR)	«найди аномалии в суммах»
detect_patterns	Паттерны в тексте (email, ИНН, телефон)	«какие паттерны в колонке email?»

Статистика и связи

Инструмент	Что делает
correlation_analysis	Корреляции между числовыми колонками (Пирсон/Спирмен)
distribution_analysis	Форма распределения (skewness, kurtosis, гистограмма)
cross_tab	Кросс-табуляция двух категорий + Хи-квадрат
pivot_table	Сводная таблица в стиле Excel (PIVOT)
statistical_test	t-тест, Mann-Whitney, KS-тест, Хи-квадрат
segment_data	Сегментация (квинтили, децилы, RFM-анализ)
compare_tables	Сравнение двух таблиц (общие/уникальные строки, расхождения)
time_analysis	Тренды, сезонность, скользящее среднее

ML и прогнозы

Инструмент	Что делает
predict_trend	Прогноз тренда (линейная/полиномиальная регрессия)
cluster_analysis	Кластеризация K-Means/DBSCAN с авто-выбором k
feature_importance	Важность признаков (Random Forest)
classify_rows	Классификация строк через LLM
semantic_search	Семантический поиск через LLM embeddings
generate_sql	Генерация SQL из описания на русском

Визуализация и отчёты

Инструмент	Что делает
visualize_data	График (bar/line/pie/scatter/area/histogram) → PNG
build_dashboard	Дашборд из 4-6 графиков одним вызовом
create_public_dashboard	Standalone HTML-дашборд с интерактивными фильтрами
data_story	Нарратив с графиками — «история данных»
export_data	Экспорт результата в CSV

Управление данными

Инструмент	Что делает
transform_data	Нормализация, one-hot, извлечение дат, binning
merge_tables	JOIN двух таблиц (с авто-определением ключей)
load_file	Загрузка CSV/Excel/Parquet в DuckDB
attach_database	Подключить новую БД в рантайме
refresh_schema	Обновить схему после изменений в БД
get_schema	Структура таблицы (колонки, типы, превью)
query_explain	План выполнения SQL (EXPLAIN)
test_connection	Проверить доступность подключения

---

Режимы работы подключений

У каждого подключения в connections.yaml есть поле mode:

Режим	Как работает	Когда использовать
auto (по умолч.)	SQL → source DB, ML → DuckDB (лениво)	Универсальный режим
remote	Всё SQL выполняется в source DB, DuckDB не используется	БД быстрая, ML не нужен
dump	Таблицы выгружаются в DuckDB при старте	Файлы, маленькие БД, офлайн
federated	Source DB прицепляется к DuckDB через расширение	Кросс-БД JOIN

Просто оставьте auto — сервер сам разберётся.

---

Поддерживаемые БД

БД	db_type	Remote SQL	Federated
PostgreSQL	postgresql	✅	✅
MySQL / MariaDB	mysql	✅	✅
ClickHouse	clickhouse	✅	—
SQLite	sqlite	✅	✅
CSV	файл	—	—
Excel (.xlsx)	файл	—	—
Parquet	файл	—	—

---

Ресурсы и промпты

Сервер предоставляет не только инструменты, но и ресурсы (данные, которые ИИ может читать) и промпты (шаблоны запросов):

Ресурсы

• schema://tables — список всех таблиц с колонками и типами (ИИ видит схему автоматически)
• schema://diagram — Mermaid ER-диаграмма таблиц и связей (рендерится в чате как картинка)
• connection://list — список подключений и их режимы
• table://{name}/preview — превью строк таблицы

Промпты

• analyze_table — системный промпт аналитика с контекстом схемы
• weekly_report — шаблон еженедельного отчёта (профиль + инсайты + тренды + экспорт)

---

LLM для классификации и поиска

Некоторые инструменты (classify_rows, generate_sql, semantic_search) требуют LLM. Есть три режима:

llm_mode	Как работает	Когда использовать
builtin	Отдельный LLM-клиент (LLM_BASE_URL/LLM_MODEL)	Ollama, vLLM, OpenAI API
sampling	Использует модель хоста (Claude/Cursor) через MCP sampling	Если у вас уже есть Claude
none	Возвращает инструкцию для хоста	Без LLM

Настройка:

LLM_BASE_URL=http://localhost:11434/v1   # Ollama, vLLM, OpenAI-compatible
LLM_MODEL=qwen2.5:14b

Работает на бюджетных LLM — достаточно модели 7B-14B.

---

Переменные окружения

Все настройки через переменные с префиксом DATASEARCHER_MCP_:

Переменная	По умолчанию	Описание
DATASEARCHER_MCP_CONNECTIONS_FILE	connections.yaml	Файл подключений
DATASEARCHER_MCP_DEFAULT_MODE	auto	Режим по умолчанию
DATASEARCHER_MCP_QUERY_TIMEOUT	60	Таймаут SQL (сек), 0 = без лимита
DATASEARCHER_MCP_AUTO_TRANSLATE	true	Авто-трансляция SQL между диалектами
DATASEARCHER_MCP_AUTH_TOKEN	``	Bearer token для HTTP auth
DATASEARCHER_MCP_CHARTS_MODE	both	json / png / both
LLM_BASE_URL	—	URL LLM API (OpenAI-compatible)
LLM_MODEL	—	Модель LLM

Полный список — в config.py.

---

Как это работает (технически)

┌──────────────┐     ┌─────────────────────────────────────────────┐
│  MCP-клиент  │     │           datasearcher-mcp                  │
│ Claude/Cursor│────▶│  FastMCP server                             │
│  VS Code     │◀────│   ├── 36 tools                              │
└──────────────┘ MCP └───┤                                   ◀──────┘
                        │  ┌─────────────────────────────────┐    │
                        │  │ Remote (push-down)              │    │
                        │  │  sql_query → source DB          │    │
                        │  │  query_explain → source DB      │    │
                        │  │  get_schema → source DB         │    │
                        │  │  + sqlglot dialect translation  │    │
                        │  └─────────────────────────────────┘    │
                        │  ┌─────────────────────────────────┐    │
                        │  │ Lazy DuckDB (ML only)           │    │
                        │  │  cluster_analysis → ensure_table│    │
                        │  │  predict_trend → ensure_table   │    │
                        │  │  feature_importance → ensure_   │    │
                        │  │  + ML cache by SQL hash         │    │
                        │  └─────────────────────────────────┘    │
                        │                                         │
                        │  resources: schema://tables             │
                        │           schema://diagram (Mermaid)    │
                        │           connection://list             │
                        │           table://{name}/preview        │
                        │  prompts: analyze_table, weekly_report  │
                        └─────────────────────────────────────────┘

Архитектура

datasearcher-mcp/
  pyproject.toml              # пакет + зависимости
  connections.example.yaml    # пример конфига
  Dockerfile                  # production-образ
  docker-compose.yml          # для быстрого старта
  src/datasearcher_mcp/
    __main__.py               # CLI: --transport, --config, --auth-token
    config.py                 # настройки (pydantic-settings)
    session.py                # DuckDB-сессия (ленивая)
    engine.py                 # движок: подключения, таблицы, remote/dump/auto
    server.py                 # FastMCP: 36 tools + 4 resources + 2 prompts
    llm_client.py             # LLM-клиент для classify/generate_sql
    embeddings.py             # semantic search через LLM embeddings
    connectors/               # коннекторы к БД (PG, MySQL, CH, SQLite)
    tools/                    # 30 инструментов анализа
    render/                   # графики (matplotlib PNG) + парсинг маркеров
    prompts/                  # системный промпт аналитика

Ключевые решения

Решение	Почему так
DuckDB выключен по умолчанию	Source DB умнее (индексы, оптимизатор). Выгрузка — только для ML
sqlglot для трансляции SQL	Пользователь пишет один SQL — работает в любой БД
Federated через DuckDB extensions	Кросс-БД JOIN без ETL
FK из information_schema	Авто-join таблиц, не просим пользователя указывать ключи
ML cache по SQL-хэшу	Повторные ML-запросы не выгружают данные повторно
MCP sampling для LLM-задач	Использует модель хоста (Claude) — не нужен отдельный LLM

Технологии

Слой	Технология
MCP	mcp[cli] 1.28 (FastMCP, stdio/SSE/Streamable HTTP)
SQL	Source DB (push-down) или DuckDB (lazy/federated)
Трансляция SQL	sqlglot (DuckDB → PG/MySQL/CH/SQLite)
ML	scikit-learn, scipy, numpy
Графики	matplotlib (PNG)
Embeddings	OpenAI-compatible /v1/embeddings
Драйверы БД	psycopg2, pymysql, clickhouse-connect, aiosqlite
Файлы	CSV/Parquet (DuckDB), Excel (openpyxl)
Дашборды	standalone HTML + DuckDB-WASM + Chart.js
Auth	Bearer token middleware (Starlette)

---

Лицензия

MIT