maxstat-mcp

# MaxStat MCP

[![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP-4830E6)](https://modelcontextprotocol.io/)
[![Tools](https://img.shields.io/badge/MCP_tools-21-4830E6)](#все-21-инструмент)
[![Version](https://img.shields.io/badge/release-1.2.1-4830E6)](CHANGELOG.md)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Official MCP Registry](https://img.shields.io/badge/Official_MCP_Registry-live-2EA44F)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.fbmdata%2Fmaxstat-mcp)
[![Glama](https://img.shields.io/badge/Glama-listed-2EA44F)](https://glama.ai/mcp/connectors/io.github.fbmdata/maxstat-mcp)

**Официальный удалённый MCP-сервер MaxStat для поиска, аналитики и мониторинга
каналов и публикаций в мессенджере MAX.**

Разработчик и оператор: **ООО «ФБМ Аналитикс» / FBM Analytics**.

[Русский](#русский) · [English](#english)

[Получить бесплатный API-токен](https://maxstat.ru/dashboard/api) ·
[Подключить MaxStat MCP](#быстрый-старт) ·
[Посмотреть все 21 инструмент](#все-21-инструмент) ·
[Инструкция для AI-установщика](llms-install.md)

![Демонстрация MaxStat MCP](assets/maxstat-mcp-demo.gif)

> MaxStat размещает и обслуживает MCP-сервер. В репозитории опубликованы
> манифесты, плагины, аналитический skill, клиентские конфигурации и
> документация. Серверная реализация и данные MaxStat не являются открытым
> исходным кодом.

## Русский

### Что именно можно получить через MaxStat MCP

AI-агент подключается к живому индексу каналов и публикаций MAX и получает
структурированные данные, а не фрагменты поисковой выдачи или вручную собранные
скриншоты.

| Область             | Какие данные возвращает MCP                                                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Поиск каналов       | Название, описание, URL, категория, тип доступа, диапазоны аудитории и числа публикаций, сортировка по релевантности, дате или аудитории    |
| Карточка канала     | ID, название, описание, аватар, URL, публичный или закрытый доступ, подписчики, публикации, категории, даты и статус РКН, когда он доступен |
| Динамика аудитории  | Дневные значения, минимум, максимум, абсолютный и процентный рост за выбранный период                                                       |
| Просмотры и реакции | Суммарные, средние и максимальные значения на публикацию и дневная история                                                                  |
| Активность канала   | Число публикаций, дневная история и распределение по тексту, фото, видео, файлам и другим форматам                                          |
| Поиск публикаций    | Полнотекстовый поиск с фильтрами по каналу, формату, датам, просмотрам и реакциям                                                           |
| Карточка публикации | Текст, URL, тип, вложения, просмотры, сумма и разбивка реакций, даты и источник пересылки                                                   |
| История публикации  | Дневные значения просмотров и реакций                                                                                                       |
| Пересылки           | Найденные репосты, их URL, даты и ID каналов назначения                                                                                     |
| Мониторинг          | Webhook на новые публикации канала или новые публикации по ключевому слову и категории                                                      |
| Тариф и расход      | Статус тарифа, период, включённые, купленные, использованные и оставшиеся кредиты и история списаний                                        |

Также можно добавить публичный или доступный по приглашению канал MAX в очередь
отслеживания MaxStat.

### Проверенный масштаб индекса

| Проверено 28 июля 2026 года |   Живой индекс |
| --------------------------- | -------------: |
| Каналы MAX                  |    **367 759** |
| Публикации                  | **85 720 012** |
| Категории каналов           |         **42** |
| MCP-инструменты             |         **21** |

Индекс постоянно растёт. Используйте `search_channels`, `search_posts` и
`get_categories`, чтобы получить актуальные результаты.

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

1. Создайте токен в
   [личном кабинете MaxStat API](https://maxstat.ru/dashboard/api).
2. Не публикуйте токен и не добавляйте его в Git.
3. Выберите платформу ниже.
4. Перезапустите клиент и проверьте, что доступны 21 инструмент MaxStat.

| Параметр             | Значение                     |
| -------------------- | ---------------------------- |
| Endpoint             | `https://maxstat.ru/api/mcp` |
| Транспорт            | Streamable HTTP              |
| Авторизация          | API-токен                    |
| Заголовок            | `X-API-Token: <API_TOKEN>`   |
| Переменная окружения | `MAXSTAT_API_TOKEN`          |

### Установка по платформам

| Платформа               | Способ                                                  |
| ----------------------- | ------------------------------------------------------- |
| Codex / ChatGPT desktop | Репозиторий-маркетплейс и нативный Codex-плагин         |
| Claude Code             | Claude-compatible marketplace                           |
| VS Code                 | Agent Plugins marketplace или прямой `.vscode/mcp.json` |
| GitHub Copilot CLI      | Общий Claude/Copilot marketplace                        |
| Gemini CLI              | Gemini extension с защищённой настройкой токена         |
| Cursor                  | Установка по ссылке или `~/.cursor/mcp.json`            |
| Windsurf                | `~/.codeium/windsurf/mcp_config.json`                   |
| JetBrains AI Assistant  | MCP-настройки IDE                                       |
| Claude Desktop          | Локальный мост `mcp-remote`                             |
| Cline                   | Удалённый Streamable HTTP из `llms-install.md`          |
| Другие клиенты          | Универсальный Streamable HTTP JSON                      |

#### Codex

До запуска Codex сохраните токен в окружении:

```bash
export MAXSTAT_API_TOKEN="<API_TOKEN>"
```

Добавьте marketplace и установите плагин:

```bash
codex plugin marketplace add fbmdata/maxstat-mcp
codex plugin add maxstat@maxstat-plugins
```

Плагин подключает MCP с правильным пользовательским заголовком
`X-API-Token`. Не используйте Bearer-настройку: она отправляет другой заголовок
и не подходит для MaxStat.

Для прямой установки без плагина объедините
[`configs/codex.toml`](configs/codex.toml) со своим
`~/.codex/config.toml`:

```toml
[mcp_servers.maxstat]
url = "https://maxstat.ru/api/mcp"
env_http_headers = { "X-API-Token" = "MAXSTAT_API_TOKEN" }
```

#### Claude Code

```bash
export MAXSTAT_API_TOKEN="<API_TOKEN>"
claude plugin marketplace add fbmdata/maxstat-mcp
claude plugin install maxstat@maxstat-plugins
```

Прямая конфигурация находится в
[`configs/claude-code.json`](configs/claude-code.json).

#### Visual Studio Code

Добавьте marketplace в `settings.json`:

```json
{
  "chat.plugins.marketplaces": ["fbmdata/maxstat-mcp"]
}
```

Откройте Extensions, найдите `@agentPlugins`, выберите `MaxStat MCP` и нажмите
Install. Для прямого подключения скопируйте
[`configs/vscode.json`](configs/vscode.json) в `.vscode/mcp.json`: VS Code
безопасно запросит токен через password input.

#### GitHub Copilot CLI

```bash
export MAXSTAT_API_TOKEN="<API_TOKEN>"
copilot plugin marketplace add fbmdata/maxstat-mcp
copilot plugin install maxstat@maxstat-plugins
```

Claude Code, VS Code и GitHub Copilot CLI используют один совместимый плагин,
skill и MCP-конфигурацию.

#### Gemini CLI

```bash
gemini extensions install https://github.com/fbmdata/maxstat-mcp
```

Расширение запросит `MAXSTAT_API_TOKEN` как чувствительную настройку и подключит
его к заголовку `X-API-Token`. Инструкции Gemini находятся в
[`GEMINI.md`](GEMINI.md).

#### Cursor

[![Add MaxStat MCP to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=maxstat&config=eyJ1cmwiOiJodHRwczovL21heHN0YXQucnUvYXBpL21jcCIsImhlYWRlcnMiOnsiWC1BUEktVG9rZW4iOiIke2VudjpNQVhTVEFUX0FQSV9UT0tFTn0ifX0%3D)

Перед запуском Cursor задайте `MAXSTAT_API_TOKEN`, затем нажмите кнопку выше.
Альтернатива: объедините
[`configs/cursor.json`](configs/cursor.json) с `~/.cursor/mcp.json`.

#### Cline

Задайте `MAXSTAT_API_TOKEN` до запуска Cline и передайте агенту
[`llms-install.md`](llms-install.md). Файл содержит конфигурацию удалённого
Streamable HTTP-сервера и проверку подключения. Локальный npm-пакет не нужен:
MaxStat размещает и обслуживает сервер на `https://maxstat.ru/api/mcp`.

#### Windsurf

Задайте `MAXSTAT_API_TOKEN` до запуска Windsurf и объедините
[`configs/windsurf.json`](configs/windsurf.json) с
`~/.codeium/windsurf/mcp_config.json`. Конфигурация использует нативную
подстановку `${env:MAXSTAT_API_TOKEN}`.

#### JetBrains AI Assistant

Откройте **Settings → Tools → AI Assistant → Model Context Protocol (MCP)**,
добавьте HTTP-конфигурацию из
[`configs/jetbrains.json`](configs/jetbrains.json) и замените `<API_TOKEN>`
локально в IDE. JetBrains пока не документирует подстановку переменной
окружения в MCP headers, поэтому placeholder оставлен намеренно.

#### Claude Desktop

Облачный custom connector Claude не принимает произвольный пользовательский
`X-API-Token`. До внедрения OAuth 2.1 используйте локальный мост из
[`configs/claude-desktop.json`](configs/claude-desktop.json). Требуются
Node.js и npm; токен сохраняется только в локальной конфигурации Claude
Desktop.

#### Универсальная конфигурация

Используйте [`configs/generic-mcp.json`](configs/generic-mcp.json):

```json
{
  "mcpServers": {
    "maxstat": {
      "type": "streamable-http",
      "url": "https://maxstat.ru/api/mcp",
      "headers": {
        "X-API-Token": "<API_TOKEN>"
      }
    }
  }
}
```

### Все 21 инструмент

####