tsheets-mcp

MCP-сервер для TSheets (QuickBooks Time) — платформы Intuit для учёта рабочего времени, планирования и отпусков (PTO). Предоставляет полный публичный REST API v1 TSheets в виде инструментов MCP.

Обзор

• HTTP-сервис без сохранения состояния. Учётные данные никогда не сохраняются — каждый запрос передаёт собственный токен доступа через заголовок, который используется только в течение жизни этого одного запроса.

• Поддерживает конкурентные запросы; изоляция учётных данных для каждого запроса выполняется через Python contextvars, а не через глобальный/общий экземпляр клиента.

• Точки входа: POST /mcp (протокол MCP) и GET /health (проверка работоспособности).

• Порт по умолчанию: 8080 (настраивается через MCP_HTTP_PORT).

• В API TSheets вообще не существует параметров-шаблонов пути — каждый идентификатор (ids, user_id и т.д.) передаётся как параметр строки запроса, даже при получении одного ресурса. Это реальная особенность дизайна API, а не упрощение, сделанное этим сервером.

Related MCP server: Timesheet MCP Server

Охват

15 инструментов, сокращённых из исходной сборки полного API на 85 инструментов (2026-08-04). Сохранённая конфигурация интеграции MSPbots для этого вендора вызывает ровно 6 конечных точек (Effective Settings, Jobcodes, Users, Customfielditem User Filters, Timesheets, Custom Fields — все GET, только чтение). Согласно решению об объёме «фактическое использование + базовые CRUD той же категории», эта сборка полностью сохраняет ровно эти 6 категорий — effective_settings (1, только чтение, для этого ресурса не существует глаголов CRUD), custom_field_item_user_filters (1, аналогично), jobcodes (3: create/retrieve/update), users (3: create/retrieve/update), timesheets (4: create/retrieve/update/delete), custom_fields (3: create/retrieve/update) — всего 15 инструментов. Все остальные категории из исходной сборки на 85 инструментов (Reports, Files, Time Off Requests (+ Entries), Schedule Events (+ Calendars), Reminders, Projects (+ Notes/Activities/Activity Replies/Activity Read Times), Notifications, Locations (+ Maps), Jobcode Assignments, Groups, Estimates (+ Items), Custom Field Items (+ Filters + Jobcode Filters), Geolocations, Timesheets Deleted, Managed Clients, Last Modified, Invitations, Geofence Configs, Current User — 28 категорий, ~70 инструментов) были полностью удалены как неиспользуемые MSPbots.

Исходные данные для сохранённых инструментов изначально были извлечены путём клонирования собственного GitHub-репозитория документации TSheets (https://github.com/tsheetsteam/api_docs) и разбора каждого частичного Markdown/ERB-файла по конечным точкам (source/includes/APIReference/<Category>/_*.md.erb) на предмет HTTP-метода, пути и таблицы параметров — тот же подход «структурированное извлечение, затем генерация кода», который используется для других вендоров с большими API в этой программе (ConnectSecure, Dynu, Jira Data Center, Opsgenie). Если удалённая категория понадобится позже, тот же источник можно повторно разобрать тем же способом.

Аутентификация

TSheets использует статический токен доступа, получаемый через собственную процедуру OAuth/API-app вендора (см. внутреннюю статью базы знаний MSPbots, на которую есть ссылка из конфигурации интеграции). Собственное соглашение об интеграции MSPbots передаёт этот токен как Authorization: Bearer <accessToken>, что соответствует документированному формату TSheets, и этот сервер пересылает его ровно таким же образом.

Описание параметров авторизации в заголовке

Отсутствие заголовка возвращает 401:

{
  "error": "Missing credentials",
  "message": "This server requires the X-TSheets-Access-Token header",
  "required_headers": ["X-TSheets-Access-Token"],
  "optional_headers": []
}

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

Конечная точка MCP

• POST /mcp — протокол MCP (потоковый HTTP-транспорт)

• GET /health — проверка работоспособности, возвращает ровно {"status": "ok"}. Это чисто локальная проверка — она не вызывает API TSheets, поэтому сбои TSheets никогда не помечают контейнер как нездоровый.

Ошибки и пагинация

• Ошибки инструментов возвращаются в виде внутриполосной JSON-обёртки (а не выброшенного исключения или ошибки уровня протокола): {"error": {"code": "...", "message": "...", "retryable": true|false}}. code — одно из значений not_configured / unauthorized / not_found / invalid_argument / rate_limited / upstream_error, сопоставленных с HTTP-статусом вышестоящего API.

• Исходящие вызовы к API TSheets используют таймаут подключения 5 с / таймаут чтения 30 с, до 3 повторов с ограниченной экспоненциальной задержкой при 429/5xx (с учётом Retry-After) и переиспользуют единый пул соединений в течение всего времени жизни процесса.

• Параметр limit каждого инструмента retrieve_* по умолчанию равен 50 и ограничивается документированным максимумом TSheets в 200 на страницу, если вызывающая сторона запрашивает больше (собственный API TSheets также по умолчанию использует и ограничивается 200, так что здесь оба предела совпадают).

Список инструментов

Имена инструментов имеют вид tsheets_<category>_<operation> и образованы от заголовка ## Heading каждой операции в исходной документации (например, «Retrieve Timesheets» в категории timesheets → tsheets_timesheets_retrieve_timesheets). Некоторые параметры фильтрации retrieve описаны как «обязательные (если не заданы X, Y или Z)» — требование «один из N», которое невозможно чисто выразить одним строго обязательным параметром Python, поэтому они смоделированы как необязательные, а ограничение ИЛИ явно описано в docstring самого инструмента. Параметры body для конечных точек create/update принимаются как универсальный dict — по соглашению самого TSheets они оборачиваются в {"data": [ {...}, ... ]} (массовое создание/обновление до 50 объектов за вызов), что документировано для каждого инструмента.

Пример тестирования

# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-TSheets-Access-Token: <your-tsheets-access-token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "tsheets_jobcodes_retrieve_jobcodes",
      "arguments": {}
    }
  }'

Проверено на живом API (2026-07-30): первый тестовый токен доступа оказался просроченным (401 invalid_grant, подтверждено идентичным результатом при прямом curl — см. примечание об ошибке ниже, где описано, что выявил этот запуск). Затем второй, только что выпущенный токен доступа был протестирован по полному циклу через этот запущенный сервер и вернул реальные данные аккаунта: tsheets_current_user_retrieve_the_current_user вернул фактическую запись текущего пользователя (имя, разрешения, остатки PTO) плюс дополнительные данные jobcode, а tsheets_jobcodes_retrieve_jobcodes (соответствует одному из 6 настроенных эндпоинтов MSPbots) вернул реальные записи jobcode. Оба подтверждают, что полный конвейер запрос/аутентификация/ответ корректно работает с живым API.

Ошибка, исправленная во время самопроверки: исходный анализатор ошибок _raise_for_status предполагал, что TSheets всегда вкладывает детали ошибки в {"error": {"message": "..."}}, но на самом деле TSheets возвращает плоский объект в стиле OAuth {"error": "invalid_grant", "error_description": "..."} при сбоях аутентификации — вызов .get() для строки "invalid_grant" падал с ошибкой 'str' object has no attribute 'get'. Это было обнаружено и исправлено с использованием первого (просроченного) тестового токена, прежде чем сервер был признан готовым.

Справочник по API

• Обзор: https://tsheetsteam.github.io/api_docs/

• Исходный код (включая официальную коллекцию Postman): https://github.com/tsheetsteam/api_docs

Известные пробелы

• Сокращено с 85 до 15 инструментов 2026-08-04. Первоначальная сборка покрывала весь публичный API, насчитывающий 34 категории, согласно более раннему решению об объёме. Более позднее решение об объёме сократило её ровно до 6 категорий, которые реально использует MSPbots (все сохранены полностью — обрезка по категориям не потребовалась, поскольку ни одна не превышала нескольких инструментов) — см. раздел Scope выше для полного списка 28 удалённых категорий (~70 инструментов). Если удалённая категория понадобится позже, исходные документы (https://github.com/tsheetsteam/api_docs) можно повторно разобрать тем же способом, каким были сгенерированы сохранённые инструменты.

• tsheets_timesheets_delete_timesheets безвозвратно удаляет записи timesheet согласно документации самого вендора — относитесь к этому как к разрушительному/необратимому действию и согласуйте с человеком перед вызовом. Остальные сохранённые инструменты create/update также изменяют реальные данные TSheets (jobcodes, пользователей, настраиваемые поля).

• Группы фильтров «обязателен один из N» смоделированы как полностью необязательные — в нескольких эндпоинтах Retrieve параметр задокументирован как «обязательный (если не задан X, Y или Z)»; выразить это как реальное ограничение в обычной сигнатуре функции невозможно, поэтому все такие параметры необязательны в сигнатуре инструмента, а требование ИЛИ подробно описано в docstring. Вызывающие должны указать как минимум один в соответствии с задокументированным ограничением, иначе живой API отклонит запрос.

• Параметры body нетипизированы (dict) вместо полного моделирования — собственная документация TSheets показывает варианты полей по типам (например, «Regular Timesheets» и «Manual Timesheets» имеют разные обязательные поля в одном и том же массиве data), которые не ложатся чисто на фиксированные типизированные параметры; справочник самого вендора (ссылка выше) документирует точную схему для каждого ресурса.