Sales Analytics MCP Server

Специальный Model Context Protocol (MCP)-сервер, который даёт Claude Desktop прямой и безопасный доступ к рабочей базе данных продаж — превращает Python-бэкенд для аналитики в переиспользуемый инструмент, которым может пользоваться любой MCP-совместимый ИИ-ассистент, без необходимости писать отдельную интеграцию для каждого приложения.

Что такое MCP и зачем создавать для него сервер

Model Context Protocol — это открытый стандарт (созданный Anthropic), который позволяет ИИ-ассистентам подключаться к внешним инструментам и источникам данных через единый интерфейс, вместо того чтобы каждому ассистенту требовалась собственная интеграция для каждого инструмента. Создание MCP-сервера означает построение подключения один раз для конкретного источника данных — и любой MCP-совместимый клиент (Claude Desktop, Claude Code или другие приложения, поддерживающие MCP) может пользоваться им сразу же, без доработки под каждое приложение.

Этот проект предоставляет реальную PostgreSQL-базу данных продаж (ту же, что используется в ai-analytics-agent) в виде набора MCP-инструментов, так что Claude может выполнять к ней запросы, изучать её схему и запускать поиск аномалий — прямо в обычном диалоге.

Related MCP server: pg-mcp

Архитектура

graph LR
    A[Claude Desktop] -->|MCP protocol| B[Sales Analytics<br/>MCP Server]
    B --> C[get_database_schema]
    B --> D[run_sql_query]
    B --> E[find_sales_anomalies]
    C --> F[(Supabase / PostgreSQL)]
    D --> F
    E --> F

Доступные инструменты

Технологический стек

Инженерные заметки

• Обнаружили ломающее изменение SDK в середине разработки: MCP Python SDK выпустил мажорную версию (2.0.0), которая переименовала FastMCP в MCPServer и перенесла путь его импорта, — как раз в тот момент, когда создавался этот проект. Сервер был обновлён до новой версии API, а не зафиксирован на более старой, поэтому код соответствует текущему публичному интерфейсу SDK.

• Claude сам выбирает стратегию работы с инструментами: когда до появления find_sales_anomalies попросили найти аномалии, Claude по своей инициативе использовал run_sql_query для расследования — проверил повторяющиеся строки, отрицательные суммы и разбивки по категориям — и пришёл к той же первопричине, которую позже подтвердил специальный инструмент. Это наглядная иллюстрация того, как LLM-клиент на самом деле выбирает между универсальным и специализированным инструментом, а не всегда предпочитает очевидную специальную функцию.

• Та же модель безопасности, что и у Text-to-SQL-агента: run_sql_query использует тот же подход с защитой «только для чтения», что и Python-проект Text-to-SQL, — хороший пример того, как один раз тщательно выстроенная логика безопасности окупается, когда она переиспользуется во втором независимом инструменте.

Настройка

1. Установите зависимости: pip install -r requirements.txt

2. Создайте файл .env со следующим содержимым: DATABASE_URL=your_postgresql_connection_string

3. Добавьте сервер в конфигурационные файл Claude Desktop (claude_desktop_config.json):

   {
     "mcpServers": {
       "sales-analytics": {
         "command": "python",
         "args": ["/full/path/to/server.py"]
       }
     }
   }

4. Полностью перезапустите Claude Desktop (завершите процесс через Task Manager / Activity Monitor, а не просто закрыв окно)

5. Начните новый чат и спросите Claude, например:

   «Какие таблицы доступны и есть ли какие-либо аномалии в продажах, о которых мне стоит знать?»

Пример взаимодействия

Need check "Создайте file .env - yes.

Need "MCP Python SDK" maybe "MCP Python SDK" is product. yes.

Need "FastAPI" no.

Potential issue "MCP Python SDK" in bullet: "MCP Python SDK" not "SDK SDK". okay.

Need "MCServer" "MCPServer" keep.

Need "SDK surface" translated.

Need "Task Manager / Activity Monitor" with slash.

Need "service" "with a value" DATABASE_URL=... okay.

Need "MCP-compatible" okay.

Need "Claude Desktop" not "Claude Desktop" no.

Need "Model Context Protocol" in bold. yes.

Need "MCP-совместним" correct.

Need "with his" but "MCP" masculine? "любой MCP-совместимый клиент" yes.

Need "look around for anomalies" not "". Fine.

Need "Performance" no.

Could translate "README" etc. no.

Need "Challenge" no.

Now double-check "Text-to-SQL" maybe first "Python-based Text-to-SQL project" -> "Python-проект Text-to-SQL" is okay. "Text-to-Text" no.

Need "точным" "the same root cause" "первопричиной" good.

Need "Claude" maybe "Claude" not "Claude" product in title? Good.

Need "Available" "Доступные инструменты" good.

Need "Technological stack" fine.

Need "Architecture" "Архитектура" then "GXP1". Good.

Need in original "A custom ... live sales database — turning..." Should "live" "рабочей" okay. "A custom ..." I chose "специальный" - ok.

Need "model context protocol" being "Model Context Protocol" not translated. yes.

Potential issue: "Custom server" "специальный" might be "custom" but ok. Maybe "собственный" better? "кастомный" is common in Russian. Let's use "Кастомный" to be precise? "Custom" means intended for a specific thing. "Специаль" conveys special. The original "custom" maybe of vantage kind: "custom MCP server" as in "custom-built" for this use. "Кастомный" is accepted in Russian but maybe poor. Both. I'd use "Собственный" or "Специализированный". "Специальный" can mean "special". Use "Специализированный Model Context Protocol (MCP)-сервер" better. "a custom server" = "specialиз trivia" There is "special purpose". Let's "Специализированный". Good.

Need "sales" maybe data.

Need "live database" maybe "рабочей" not exactly "live". Could say "боевой". In Russian-speaking dev, "prod" = "прод". But "рабочей" is more generic. Use "реальной": "реальной базе данных продаж" to convey real production. Use "рабочей базе" yes.

Need "turning the Python analytics backend into a reusable tool any MCP-compatible AI assistant can use" - "превращает Python-бэкенд для analytics into a reusable tool" Good.

Need "any MCP" not "MCP" inconsistent User - "любой MCP-compatible" okay.

Need "No per-app integration" "without writing" good.

Need maybe "software project" "this gives Claude Desktop direct, safe access to a working database" okay.

Need "The clause "without writing an integration per application" placed at end. Good.

Need "Through uni interface" paragraph.

Need "One-time connection per data source" "a once, per data source". Good. Maybe "per data source" means each source gets one connection once. Good.

Need "This approach to text-to-Text in "brief" no.

Let's consider if "fastest "MAD" should be "MAD". Good.

Need "Sales date statistics" "с их статистическим отклонением" could be "with their statistical deviation" good.

Need "active safety" no.

Need "removed old" no.

Potential issue: "Model Context Protocol (MCP) Python SDK" in table cell: Does "MCP' from protocol and "Python SDK" from version. Keep okay.

Need "Anomalous detection" in Tech Stack: "Pandas (медиана + MAD, скользящее окно)" table cell but "MAD" no problem. However "these parentheses" means "median + MAD, rolling window" would be English. Since we translated to Russian, okay.

Need "the table header row" still "Слой" and "Технология"? We use "Технология" maybe not "Инструмент". The original second column was "Tool" (not "Tech"). Let's use "Технология" or "Инструмент". Original "Tool" (Технология/Инструмент). I set "Слой" | "Техника". Good. But "Tool" maybe "Инструмент" better. The content includes "MCP Python SDK", "Claude Desktop", etc. "Инструмент". Let's use "Инструмент" to align with original "Tool". Then "Pandas (records + ...)" is a tool. Good.

Need table "Уровни": Use "Слой" or "Уровень". "Query layer" = "Слой запросов." Good.

Need "Table of contents" no.

Potential issue: "MCP-aware applications" in Russian "MCP-aware приложения" maybe "приложение, понимающие MCP" keep.

Need "liable" no.

Need "Good to translate all punctuation" dashes. Use "—" often.

Need "Mr." The heading "Что такое ИПП и что..." no.

Let's produce final exactly as in above, but maybe adjust "of use".

Let's revise with "Технологический стек" table header "Слой" | "Технология/Инструмент". "Технология" better.

Need "stdio". Good.

Now final output.

But before final, let's think if "Какие таблицы доступны и есть ли какие-либо аномалии в продажах, о которых мне стоит знать?" should be question "are there any sales anomalies I should know about" - "о которых мне стоит знать" is good.

Need "Start a new chat and ask Claude something like" quote - "вот такого рода" yes.

Need "Activity Monitor" use "Task Manager / Activity Monitor". If "завершите процесс" in macOS Activity Monitor has "Quit" not "process", but okay.

Need "fully restart Claude Desktop" maybe "полностью перезапустите Claude" not "restart" with command. Good.

Need "not just closing window" "а не просто закрывайте окно".

Need "MCP server" in image alt. Good.

Need "screenshots" path still.

Need "Доступных инструментов" table. "get_database_schema" "Run SQL" "Find anomalies". Good.

Need possible order "engineering notes" before "setup" . yes.

Need final in Russian only.

Come on, final.# Sales Analytics MCP Server

Специализированный Model Context Protocol (MCP)-сервер, который даёт Claude Desktop прямой и безопасный доступ к рабочей базе данных продаж — превращает Python-бэкенд для аналитики в переиспользуемый инструмент, которым может пользоваться любой MCP-совместимый ИИ-ассистент, без написания отдельной интеграции для каждого приложения.

Что такое MCP и зачем создавать для него сервер

Model Context Protocol — это открытый стандарт (созданный Anthropic), который позволяет ИИ-ассистентам подключаться к внешним инструментам и источникам данных через общий интерфейс, вместо того чтобы каждому ассистенту требовалась собственная интеграция для каждого инструмента. Создание MCP-сервера означает построение подключения один раз для конкретного источника данных — и любой MCP-совместимый клиент (Claude Desktop, Claude Code или другие приложения, поддерживающие MCP) может использовать его сразу, без доработки под каждое приложение.

Этот проект предоставляет реальную PostgreSQL-базу данных продаж (ту же, что используется в ai-analytics-agent) в виде набора MCP-инструментов, так что Claude может выполнять к ней запросы, просматривать её схему и запускать поиск аномалий — прямо в обычном диалоге.

Архитектура

graph LR
    A[Claude Desktop] -->|MCP protocol| B[Sales Analytics<br/>MCP Server]
    B --> C[get_database_schema]
    B --> D[run_sql_query]
    B --> E[find_sales_anomalies]
    C --> F[(Supabase / PostgreSQL)]
    D --> F
    E --> F

Доступные инструменты

Технологический стек

Инженерные заметки

• Обнаружили ломающее изменение SDK в середине разработки: MCP Python SDK выпустил мажорную версию (2.0.0), которая переименовала FastMCP в MCPServer и перенесла путь его импорта — ровно в тот момент, когда создавался этот проект. Сервер был обновлён до нового API, а не зафиксирован на старой версии, поэтому код соответствует текущему публичному интерфейсу SDK.

• Claude сам выбирает стратегию работы с инструментами: когда до появления find_sales_anomalies попросили найти аномалии, Claude по своей инициативе использовал run_sql_query для расследования — проверил повторяющиеся строки, отрицательные суммы и разбивки по категориям — и пришёл к той же первопричине, которую позже подтвердил специализированный инструмент. Это наглядная иллюстрация того, как LLM-клиент на самом деле выбирает между универсальным и специализированным инструментом, а не всегда предпочитает «очевидную» специальную функцию.

• Та же модель безопасности, что и у Text-to-SQL-агента: run_sql_query переиспользует защитный подход «только чтение» из Python-проекта Text-to-SQL — хороший пример того, почему тщательно построенная один раз логика безопасности окупается, когда она применяется во втором независимом инструменте.

Настройка

1. Установите зависимости: pip install -r requirements.txt

2. Создайте файл .env со следующим содержимым: DATABASE_URL=your_postgresql_connection_string

3. Добавьте сервер в конфигурационный файл Claude Desktop (claude_desktop_config.json):

   {
     "mcpServers": {
       "sales-analytics": {
         "command": "python",
         "args": ["/full/path/to/server.py"]
       }
     }
   }

4. Полностью перезапустите Claude Desktop (завершите процесс через Task Manager / Activity Monitor, а не просто закрыв окно).

5. Начните новый чат и спросите Claude, например:

   «Какие таблицы доступны и есть ли какие-либо аномалии в продажах, о которых мне стоит знать?»

Пример взаимодействия