helpcrunch-mcp

MCP-сервер для HelpCrunch REST API v1. Инструменты только для чтения — предназначен для поиска и анализа чатов, сообщений и клиентов.

Инструменты

| Инструмент | Что делает | |---|---| | search_chats | Поиск чатов по фильтрам: статус, оценка (rating), даты, ассигни, департамент, email клиента | | list_chats | Список всех чатов с пагинацией и сортировкой | | get_chat | Один чат по id (метаданные) | | get_chat_messages | Сообщения чата — сам диалог (новые сверху, пагинация) | | search_customers | Поиск клиентов по email, имени, компании, тегам и т.д. | | get_customer | Профиль клиента по id | | list_agents | Список агентов команды | | list_departments | Список департаментов | | get_organization | Статус организации (команда онлайн, чат включён) |

Все UNIX-таймстемпы в ответах дублируются полем *ISO с читаемой датой.

Установка

git clone [email protected]:yoldar/helpcrunch-mcp.git
cd helpcrunch-mcp
npm install
npm run build

API-ключ

В HelpCrunch: Settings → Developers → Public API (не используйте Legacy API Key). Ключ можно передать двумя способами:

• аргументом командной строки: --api-key ваш_ключ
• переменной окружения: HELPCRUNCH_API_KEY

Аргумент имеет приоритет над переменной окружения. Аналогично можно переопределить адрес API: --api-url / HELPCRUNCH_API_URL.

Подключение

Claude Desktop / любой MCP-клиент (через npx)

В claude_desktop_config.json:

{
  "mcpServers": {
    "helpcrunch": {
      "command": "npx",
      "args": ["helpcrunch-mcp", "--api-key", "ваш_ключ"]
    }
  }
}

Или с ключом в env:

{
  "mcpServers": {
    "helpcrunch": {
      "command": "npx",
      "args": ["helpcrunch-mcp"],
      "env": {
        "HELPCRUNCH_API_KEY": "ваш_ключ"
      }
    }
  }
}

Claude Code

claude mcp add helpcrunch -- npx helpcrunch-mcp --api-key ваш_ключ

Из локальной сборки (без npm)

{
  "mcpServers": {
    "helpcrunch": {
      "command": "node",
      "args": ["/путь/к/helpcrunch-mcp/dist/index.js", "--api-key", "ваш_ключ"]
    }
  }
}

Заметки

• Лимит HelpCrunch API — 120 запросов в минуту; при превышении сервер вернёт понятную ошибку 429.
• Максимум 100 записей на страницу — для полной выборки используйте offset.
• Даты в фильтрах (chats.createdAt и т.п.) — UNIX-таймстемпы в секундах.
• Статусы чатов: new, opened, pending, onhold, no communication, closed. Оценки: great, average, poor.