TimelinesAI MCP Server

MCP-сервер (Model Context Protocol), который открывает публичный API TimelinesAI — входящие WhatsApp-сообщения для команд — для Claude. Предназначен для развёртывания в Railway в режиме только для чтения.

👉 Шаги по развёртыванию — в DEPLOY-RAILWAY.md.

Что делает

Даёт Claude 12 инструментов для чтения инбокса и работы с ним: чаты, сообщения, метки, ответственные, подключённые номера и команда — плюс универсальный инструмент, инструмент обнаружения и агрегированная сводка по инбоксу.

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

Три заслона

Этот MCP общается с реальными людьми. Отправленное сообщение в WhatsApp доходит до телефона собеседника за секунды и не подлежит отмене. Поэтому здесь три независимых замка.

1. TIMELINES_READ_ONLY — значение по умолчанию зависит от транспорта

• stdio (локально): записывающие операции разрешены по умолчанию.

• http (удалённо): записывающие операции заблокированы по умолчанию.

Забыть эту переменную в публичном развёртывании — значит оставить его в режиме только для чтения.

2. TIMELINES_ALLOW_SEND — заслон отправки

Выключен по умолчанию на обоих транспортах, даже локально. Даже если вы разрешите запись, отправка сообщений останется заблокированной, пока не установите TIMELINES_ALLOW_SEND=1.

Причина — асимметрия: изменить метку переназначить чат или закрыть его — это внутренние и обратимые действия. Отправить WhatsApp клиенту — уже необратимое. Здесь и должен быть отдельный переключатель.

3. confirm=true — заслон на каждую операцию

Каждая отправка требует confirm=true и всего остального, точно так же, как удаление файла, перенастройка вебхука или отзыв доступа у коллеги. Инструкция инструмента как раз такая: сначала показать пользователю точного получателя и точный текст и только после его подтверждения — отправлять.

Каждый отказ сообщает, какой именно из трёх заслонов его остановил.

Аутентификация эндпоинта

Протокол MCP не включает собственную аутентификацию. В режиме http этот сервер требует в каждом запросе Authorization: Bearer <MCP_AUTH_TOKEN>, или секрета, встроенного в маршрут (/s/<секр>/mcp), для коннекторов Claude. /healthz — единственный публичный маршрут.

Сервер отказывается запускаться, если MCP_AUTH_TOKEN отсутствует или содержит меньше 32 символов.

Локальный запуск

pip install -r requirements.txt

# stdio (para Claude Desktop)
TIMELINES_API_TOKEN=tla_xxx python timelines_mcp.py

# http (como en Railway)
TIMELINES_MCP_TRANSPORT=http \
TIMELINES_API_TOKEN=tla_xxx \
MCP_AUTH_TOKEN=$(python3 -c "import secrets;print(secrets.token_urlsafe(48))") \
PORT=8000 python timelines_mcp.py

При запуске печатает, в каком режиме он оказался:

[timelines-mcp] streamable-http on 0.0.0.0:8000  token=set  read_only=True  allow_send=False  sending_enabled=False

Заметки об API TimelinesAI

Проверялось на публичной документации (https://timelines.ai/docs/public-api-reference/overview):

• Базовый URL: https://app.timelines.ai/integrations/api, авторизация Authorization: Bearer <tla_...>.

• Тело запросов — JSON, не form-encoded.

• Ответы приходят в обёртке: {"status":"ok","data":{...}}. Существуют сбои, которые приходят с HTTP 200 и status:"error" — этот сервер выкручивает их как ошибку, а не как успех, иначе неудавшаяся отправка выглядела бы как отправленная.

• Сообщения об ошибках содержат детализацию по полям: {"status":"error","message":..., "error_code":...,"errors":[{"fields":["phone"],"msg":"..."}]}. Они показываются как есть в тексте ошибки.

• Фильтры с несколькими значениями передаются через запятую в одном параметре (label=vip,enterprise), не повторными параметрами и не в скобках. Список из этой функции в Python как раз подходит.

• Размер страницы фиксированный — 50 записей, и его нельзя изменить. Проверено на живом API 2026-08-25: limit, per_page, page_size, size, count, take и rows игнорируются, а каждая страница содержит 50 записей. Единственный параметр, который работает — page, и has_another_pages в ответе говорит, есть ли ещё страница. Поэтому инструменты не предоставляют per_page: это был бы параметр который из-за видимости меняет размер, а на деле ничего не меняет.

• Чтобы уменьшить размер ответа, не получится взять маленькую страницу — вместо этого нужно сильнее фильтровать или использовать fields, чтобы оставить только нужные ключи. Сообщения — самый показательный случай: чат на 50 сообщений без труда выйдет за лимит символов. fields=["uid","text","from_me","timestamp"] оставляет психологическую суть переписки в доли от полного ответа.

• Внимание на повторение имён полей: в записи сообщения есть свой ключ data, который является словарём метаданных, в дополнение к data из общей обёртки. Поэтому fields решает, что убрать, по позиции (внутри списка — одна запись), а не по имени ключа.

• Телефоны — в международном формате с +: +5215512345678. Модель проверяет их перед отправкой в сеть и удаляет лишние пробелы и дефисы.

• Текст ограничен 2000 символами; метки — 64; названия чатов — 256.

• Если не указать whatsapp_account_number, TimelinesAI отправит с наиболее давно использованного номера — и это не часто тот, который пользователь имел в виду. Если подключено несколько номеров — лучше задавать имя явно.

• Между отправками ставится пауза ~2 секунды в соответствии с правилами WhatsApp, а каждая отправка расходует кредиты (1 текст без вложений, 2 с вложением; неотправленные возвращаются).

• Вот три разных лимита, их не нужно путать:

  Лимит	Значение	Распространяется на
  Частота запросов	50 запросов в минуту на workspace	все, даже на чтение
  Месячный объём	200,000 вызовов в месяц	все
  Квота сообщений	по тарифу (кредиты)	только отправка и отправка

  Первый — самый ощутимый: при превышении возвращается 429 too many requests в середине обработки, а не в начале.

  Сервер защищается на двух уровнях, оба они в прикладном слое, поэтому все инструменты защищены, и не только те, которые ходят по страницам:

  1. Общий ритм. Запросы следуют с интервалом 1,2 с (± 1,2 с); одиночный запрос не ожидает ни одной секунды, задержка возникает только при попытке приложений. А лимит общий на workspace, и все инструменты работают с одним workspace, поэтому и ограничитель первый.

  2. Повтор с Retry-After. Если на чтение пришёл 429, выполняется ещё одна попытка с точным интервалом, которое указал сервер. Отправка никогда не повторяется автоматически: сообщение, которое, возможно, уже было отправлено, не отправляется повторно по догадке.

  timelines_activity_summary при этом возвращает только то, что успел посчитать, и добавляет stopped_early в том случае, если его прервали. Для вопросов о конкретном человеке удобнее задать фильтр (responsible=someone@...), а не перебирать страницы: один запрос вместо двух десятков. Можно попросить увеличить лимиты, написав на hello@timelines.ai.

• Агрегирующего endpoint нет. Поэтому timelines_summary_summary листает страницы и считает суммарную статистику на стороне MCP-сервера, а чтобы конец вычисления был показан, использует complete=false, если счётчик был прерван.

Безопасность

• Секреты хранятся в переменных окружения, никогда в коде. .gitignore исключает файлы .env.

• Токен TimelinesAI даёт доступ ко всему workspace: всем разговорам WhatsApp команды с их телефонами и их содержимым. Это данные одача реальных клиентов — относись к ним соответственно.

• Единственный общий токен означает, что нет никакой прослеживаемости до действий конкретного человека.

• Чтобы отозвать доступ в один момент: отзовем токен в панели TimelinesAI — сервер сразу окажется бесполезным.