clickup-mcp-full

MCP-сервер для ClickUp, который может прочитать всё вложенное дерево подзадач одним вызовом.

Он оборачивает @twofeetup/clickup-mcp, а не форкает его, поэтому исправления из апстрима приходят вместе с обновлением зависимости. Поверх этого сервера он добавляет get_task_tree, переписывает одно описание инструмента, которое стабильно вводит в заблуждение небольшие модели, и закрепляет разумный набор инструментов по умолчанию.

Зачем

Единственный путь апстрима к подзадачам — search_tasks с include_subtasks, который вызывает GET /task/{id}?subtasks=true и возвращает полные объекты задач только для прямых детей. Для задачи с пятьюдесятью подзадачами, вложенными на несколько уровней вглубь, это одновременно и неполно, и губительно для контекстного окна агента. Альтернатива — по одному запросу на узел — ещё хуже.

get_task_tree вместо этого один раз обходит содержащий список. GET /list/{id}/task?subtasks=true от ClickUp возвращает каждую задачу в списке вместе с её указателем parent, поэтому дерево собирается локально: всего два запроса независимо от глубины или ширины, а на выходе — одна компактная строка на задачу.

Task tree for 86capt3b: 23 task(s) including the root.
Statuses: in progress: 3, open: 14, complete: 6
List: Q3 Delivery

86capt3b  [in progress]  Migrate billing service  <ivan>
  86captk1  [complete]  Audit current schema  <olena>
  86captk2  [in progress]  Write migration scripts  <ivan>
    86captm7  [open]  Handle partial refunds
    86captm8  [open]  Backfill historical rows
  86captk3  [open]  Cutover plan

Related MCP server: ClickUp MCP

Установка

Клонировать и собирать ничего не нужно. Укажите агенту на пакет — он будет загружен при первом запуске.

Claude Code

claude mcp add clickup_full_local \
  --env CLICKUP_API_KEY=pk_your_token \
  --env CLICKUP_TEAM_ID=9012345678 \
  -- npx -y github:breckenreed/clickup-mcp-full

Claude Desktop, Cursor, Windsurf или любой клиент, использующий JSON mcpServers

{
  "mcpServers": {
    "clickup_full_local": {
      "command": "npx",
      "args": ["-y", "github:breckenreed/clickup-mcp-full"],
      "env": {
        "CLICKUP_API_KEY": "pk_your_token",
        "CLICKUP_TEAM_ID": "9012345678"
      }
    }
  }
}

Hermes (~/.hermes/config.yaml)

mcp_servers:
  clickup_full_local:
    command: npx
    args: ["-y", "github:breckenreed/clickup-mcp-full"]
    env:
      CLICKUP_API_KEY: "${CLICKUP_API_KEY}"
      CLICKUP_TEAM_ID: "${CLICKUP_TEAM_ID}"
    connect_timeout: 60
    keepalive_interval: 60
    idle_timeout_seconds: 1800

Глобальная установка, если вы предпочитаете не резолвить с GitHub при каждом запуске:

npm install -g github:breckenreed/clickup-mcp-full

затем используйте clickup-mcp-full как команду без аргументов.

Учётные данные

Личный токен ClickUp не имеет собственных областей действия. Он действует от имени пользователя, который его создал, и наследует права этого пользователя, поэтому если вам нужен агент, который не может писать, создайте токен в учётной записи ClickUp с доступом только на просмотр, а не полагайтесь на выбор инструментов.

Инструменты

Апстрим также поставляет attach_file_to_task, который загружает локальный файл в ClickUp. Здесь он выключен по умолчанию: для агента, работающего без подтверждения каждого действия, он превращает любую prompt-инъекцию, которую читает агент, в путь утечки данных. Включите его осознанно, если он вам нужен:

ENABLED_TOOLS=get_workspace_hierarchy,search_tasks,manage_task,task_comments,get_container,manage_container,find_members,operate_tags,task_time_tracking,attach_file_to_task

Параметры

Увеличьте REQUEST_SPACING в общем рабочем пространстве. Значение по умолчанию допускает около десяти запросов в секунду, тогда как лимит ClickUp на токен составляет примерно 100 в минуту на большинстве тарифов. Лимит учитывается для токена, а не для инструмента, поэтому агент, который его исчерпывает, также ломает все остальные интеграции, работающие под тем же токеном. 700 удерживает вас под потолком 100 в минуту.

Примечания о поведении

Подзадачи в другом списке. Дерево строится обходом списка, который содержит корневую задачу. Если ваше рабочее пространство помещает подзадачи в список, отличный от списка их родителя, они не появятся, и сервер вернётся к прямым детям, сообщаемым конечной точкой задачи. Откройте issue, если вы с этим столкнулись и это важно.

Описания search_tasks. Описание из апстрима («Работает 3 способами») приводит к тому, что небольшие модели помещают простой id вроде 86capt3b в customTaskId, который предназначен только для id с префиксом, например DEV-123. Такой вызов проваливается в ветку поиска по рабочему пространству и завершается ошибкой «Требуется хотя бы один параметр фильтра» — ошибкой, которая называет не ту проблему, после чего модель склонна выдумывать фильтры вместо того, чтобы исправить поле. Этот сервер заменяет это описание единственным правилом, которое модели действительно нужно.

Запуск внутри Docker с home, смонтированным через bind. Если ваш агент запускает MCP-серверы с HOME, указывающим на bind-mount, npx пересобирает свой кэш пакетов через этот mount при каждом подключении, что может занять минуты и привести к тайм-ауту. Вместо этого установите глобально внутри образа и укажите command: на бинарник.

Устранение неполадок

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

CLICKUP_API_KEY=pk_... CLICKUP_TEAM_ID=... npx -y github:breckenreed/clickup-mcp-full --help

Missing required environment означает, что переменные не дошли до процесса: большинство клиентов требуют их в собственном блоке env сервера, а не в вашей оболочке.

Ошибка 401 от любого инструмента означает, что токен неверен или был отозван. Ошибка 429 означает, что вы упираетесь в лимит запросов, поэтому увеличьте REQUEST_SPACING.

Лицензия

MIT, как и апстрим-сервер, который он оборачивает. @twofeetup/clickup-mcp — это MIT-лицензированное продолжение сообществом дерева @taazkareem/clickup-mcp-server до его перехода на платную модель.