ClickUp MCP Server

Сервер Model Context Protocol для ClickUp, построенный на двух идеях:

Всё использует человеческие имена. find(scope: "Cavalry/Findings", assignee: "me", due: "overdue") — никаких ID, никакого обхода дерева для их поиска. Имена, которые не удаётся разрешить, вызывают ошибку с перечислением допустимых вариантов, потому что уверенно пустой результат хуже, чем сбой.

Вы выбираете, что он может делать. Четыре профиля возможностей, применяемые к каждому исходящему запросу. Дайте неконтролируемому агенту профиль agent — и он сможет создавать задачи и комментарии, но не сможет изменять или удалять ничего из уже существующего.

18 инструментов, 354 теста. Версия 4.3.0 — см. CHANGELOG.md. Сильно переработанный форк nsxdavid/clickup-mcp-server.

Статус: 4.x — новая. Она прошла пять раундов adversarial red-team, но ещё не работала в продакшене. Предыдущая линия 3.x по-прежнему поставляется в этом репозитории и именно её запускает эталонное развёртывание — см. Запуск 3.x.

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

Получите токен в ClickUp → Settings → Apps → API Token (он начинается с pk_). Рабочее пространство обнаруживается автоматически — больше ничего настраивать не нужно.

Без установки:

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["-y", "github:benthesoundguy/clickup-mcp-server"],
      "env": { "CLICKUP_API_TOKEN": "pk_your_token_here" }
    }
  }
}

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

git clone https://github.com/benthesoundguy/clickup-mcp-server
cd clickup-mcp-server
npm install          # builds automatically
npm run check        # verifies the token and connects — do this before wiring up a client

{
  "mcpServers": {
    "clickup": {
      "command": "node",
      "args": ["/absolute/path/to/clickup-mcp-server/build/v4/index.js"],
      "env": { "CLICKUP_API_TOKEN": "pk_your_token_here" }
    }
  }
}

Куда вставляется этот блок

Приведённая выше форма работает как есть в Claude Desktop, Claude Code, Cursor, Cline и Windsurf — все они используют ключ mcpServers. Два клиента отличаются:

• VS Code (.vscode/mcp.json) использует servers вместо mcpServers. Внутренняя форма та же. Копирование конфигурации Cursor без изменений — самая частая ошибка при настройке.

• Zed (settings.json) использует context_servers и вкладывает команду:

  { "context_servers": { "clickup": { "command": { "path": "node", "args": ["/path/to/build/v4/index.js"] } } } }

Claude Code может вообще пропустить файл:

claude mcp add clickup --env CLICKUP_API_TOKEN=pk_... -- npx -y github:benthesoundguy/clickup-mcp-server

Размещение токена в файле

Если вы предпочитаете не вставлять токен в конфигурацию клиента — настольные приложения перезаписывают эти файлы и могут сохранить устаревшую копию — поместите его в .env рядом с установкой и полностью опустите блок env:

echo 'CLICKUP_API_TOKEN=pk_your_token_here' > .env

Сервер ищет в <cwd>/.env, <install>/.env и <install>/../.env в таком порядке и сообщает, какой из них использовал при запуске. Токен из файла имеет приоритет над окружением, поэтому его ротация в одном месте действительно вступает в силу. Все остальные настройки работают наоборот — явное значение в конфигурации клиента всегда побеждает, так что случайный .env никогда не сможет расширить MCP_PROFILE. Установите MCP_STRICT_ENV=1 на сервере, чтобы полностью отключить этот поиск.

Когда что-то не работает

npm run check          # from a clone
node build/v4/index.js --check

Это выводит все входные данные, которые сервер разрешил — какой .env он нашёл и что применил, присутствует ли токен и правильной ли он формы, активный профиль и количество инструментов, версию Node и метку сборки — а затем реально подключается к ClickUp и сообщает, кто вы и каков ваш лимит запросов. Токен никогда не выводится, поэтому вывод можно безопасно вставлять в issue.

Если токен отсутствует, сервер не умирает молча в режиме stdio. Он запускается, регистрирует свои инструменты, и каждый вызов отвечает, что не так и как это исправить, так что проблема появляется в вашем разговоре, а не в лог-файле, который нужно искать. (В режиме HTTP он всё же завершается с кодом 1 — неконтролируемое развёртывание должно громко падать.)

Related MCP server: ClickUp MCP Server

Профили возможностей

Один бинарник, четыре профиля, выбираемых с помощью MCP_PROFILE. Установите один раз и добавьте запись клиента для каждого профиля, включая тот, который нужен конкретному агенту.

Стоимость схемы — это то, что определения инструментов потребляют в контексте модели при каждом запросе, до начала любой работы. Для сравнения, 3.x стоит ~18 600 токенов для 88 инструментов.

agent — самый интересный. Он может добавлять, но никогда не изменять и не уничтожать, так что худшее, что может сделать неконтролируемый агент, — создать мусор, который вы можете удалить. Эта гарантия обеспечивается тремя уровнями, и только третий является границей безопасности:

1. Фильтрация инструментов — какие инструменты вообще появляются (стоимость контекста + выбор инструментов)

2. Фильтрация действий — какие действия рекламирует инструмент (стоимость контекста + честность)

3. Политика записи — список разрешений, проверяемый для каждого исходящего запроса, включая загрузки ← гарантия

Уровни 1 и 2 зависят от того, что каждый будущий контрибьютор правильно пометит каждый инструмент. Уровень 3 — нет: он проверяет фактический запрос на выходе, поэтому неправильно помеченный инструмент, рефакторинг или добавленная в следующем году конечная точка не могут расширить профиль. Тестовый набор доказывает это, вызывая обработчики, доступные только для core, напрямую с контекстом agent — полностью обходя уровни 1 и 2 — и утверждая, что ничего не достигает провода.

Вещи, которые выглядят аддитивными, но намеренно исключены из agent: прикрепление тега, установка пользовательского поля и добавление зависимости — всё это изменяет существующую задачу; создание вебхука начинает потоковую передачу ваших данных на внешнюю конечную точку. Только добавление и безопасность — не одно и то же свойство.

Почему по умолчанию core, а не full

full предоставляет администрирование участников — приглашение пользователя потребляет платное место, удаление меняет доступ реального человека — плюс вебхуки, которые отправляют данные рабочего пространства за пределы сайта. Ничто из этого не нужно для первого подключения, и значение по умолчанию, которое никто не меняет, должно быть безопасным. Просите администрирование по имени, когда оно вам нужно; пока вы этого не сделаете, отказ скажет вам точно, как это сделать.

Вложения и файловая система

attach читает файл с машины, на которой работает сервер. Это ресурс, который политика записи не видит — она проверяет URL, а у чтения файла нет URL — поэтому он управляется отдельно через CLICKUP_ATTACH_ROOT:

• Установлен → чтение ограничено этим каталогом. Ограничение проверяется по реальному пути файла, после разрешения .. и всех симлинков.

• Не установлен → core и full могут читать любой файл, который может процесс. При agent attach вообще не предлагается (12 инструментов вместо 13), потому что нет безопасного корня по умолчанию: рабочий каталог обычно является каталогом проекта, где живёт .env.

Неправильно настроенный корень приводит к фатальной ошибке при запуске, а не игнорируется — граница, которой молча нет, хуже, чем её отсутствие.

Инструменты

Инструменты сужаются, а не исчезают там, где это имеет смысл: при read comment показывает только свои аргументы для чтения, а checklist рекламирует только list, так что схема говорит правду о том, что может это подключение, вместо того чтобы рекламировать действия, которые будут отклонены.

Правило, которому всё следует

Никогда не возвращайте уверенно неправильный ответ. ClickUp легко ошибиться, потому что он отвечает на плохой ввод бодрой бессмыслицей:

Поэтому этот сервер разрешает имена и вызывает ошибку при неоднозначности («Findings», совпадающий с четырьмя списками, — это ошибка с перечислением всех четырёх, а не подбрасывание монеты); вызывает ошибку, а не возвращает пусто, когда значение фильтра не разрешается; проверяет перечисления на стороне клиента на соответствие тому, что список действительно принимает; проверяет записи, которым не может доверять, читая объект обратно; и никогда не завышает количество — запрос, который остановил пагинацию, сообщает 100+ совпадений, а любой клиентский фильтр сообщает, сколько он фактически просканировал.

Ошибки говорят, что не удалось, почему и что делать дальше, с перечислением допустимых вариантов.

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

Удалённый режим (Claude web + mobile и любой HTTP-клиент)

Сервер говорит на потоковом HTTP и принимает три независимых учётных данных. Любое из них аутентифицирует запрос; они предназначены для сосуществования, потому что разные клиенты могут предъявлять разные вещи.

MCP_TRANSPORT=http MCP_AUTH_TOKEN=$(openssl rand -hex 24) \
MCP_PROFILE=core CLICKUP_API_TOKEN=... node build/v4/index.js

GET /health — неаутентифицированный зонд, сообщающий версию, активный профиль, количество инструментов и корень вложений.

OAuth (что нужно размещённым клиентам)

Этому серверу не нужно быть OAuth-провайдером, и он им не является. Начиная со спецификации MCP от 2025-06-18, MCP-сервер — это ресурсный сервер: он называет сервер авторизации, которому доверяет, и проверяет токены, выпущенные этим сервером. Вход, согласие и выпуск токенов относятся к вашему IdP — Cloudflare Access, WorkOS, Auth0, Descope, Stytch, Keycloak, что угодно с OIDC discovery.

MCP_TRANSPORT=http \
MCP_PUBLIC_URL=https://mcp.example.com \
MCP_OAUTH_ISSUER=https://your-idp.example.com \
CLICKUP_API_TOKEN=pk_... node build/v4/index.js

Это вся конфигурация. Затем сервер:

• обслуживает RFC 9728 Protected Resource Metadata по адресу /.well-known/oauth-protected-resource, называя вашего издателя, без аутентификации;

• отвечает на неаутентифицированный запрос кодом 401 и заголовком WWW-Authenticate, указывающим на этот документ — так клиент узнаёт, где войти;

• обнаруживает ключи подписи вашего издателя через /.well-known/openid-configuration (или RFC 8414) или использует MCP_OAUTH_JWKS_URL, если вы его задали;

• проверяет каждый токен: RS256 зафиксирован, подпись по JWKS издателя, exp, nbf, iss и aud — токен должен называть этот сервер.

Последняя проверка — самая важная. Без неё токен, выпущенный вашим IdP для другого сервиса, можно было бы воспроизвести здесь. Именно поэтому MCP_PUBLIC_URL требуется, а не выводится: ожидаемая аудитория никогда не должна приходить из запроса, потому что заголовок Host задаётся вызывающей стороной.

MCP_AUTH_TOKEN становится необязательным, как только настроен издатель — развёртывание только с OAuth не нуждается в общем пароле, который оно никогда не использует.

Примечание о Dynamic Client Registration. Спецификация от 2026-07-28 объявила DCR устаревшим в пользу Client ID Metadata Documents. Это изменение касается серверов авторизации и клиентов; ресурсный сервер в любом случае не затрагивается, что является веской причиной делегировать, а не создавать собственный AS.

Ограничение коннектора claude.ai

Пользовательский интерфейс коннектора Claude принимает только поля OAuth — Authorization URL, Token URL, Client ID, Client Secret. Поля для статического bearer-токена или пользовательского заголовка нет (#112, #411). Итак:

• С настроенным OAuth подключите его как обычный пользовательский коннектор. Это предполагаемый путь.

• Без OAuth единственный способ — форма токена в URL, /mcp/<token>, включаемая с помощью MCP_ALLOW_TOKEN_IN_PATH=1. Это работает, но помещает учётные данные в URL, где прокси их логируют, поэтому строгий режим это запрещает. Относитесь к этому как к обходному пути, а не к развёртыванию.

Cloudflare Access (необязательный третий режим аутентификации)

Задайте CF_ACCESS_TEAM_DOMAIN и CF_ACCESS_AUD, и сервер проверяет заголовок Cf-Access-Jwt-Assertion, который Access добавляет к каждому пересылаемому запросу: RS256 по JWKS команды, плюс exp, iss и aud. Оба потока Access проверяются одним путём — браузерный вход несёт email, сервисный токен несёт common_name.

Это эшелонированная защита. Запрос, достигающий источника без прохождения через Access — неправильная конфигурация туннеля, второй вход, что-то в сети хоста — не может выдать себя за аутентифицированного через Access вызывающего. Он отказывает по умолчанию: alg зафиксирован на RS256 (поэтому alg: none и путаница с HS256 отклоняются), недоступный JWKS отказывает, а не пропускает, и URL JWKS берётся из конфигурации, никогда из токена.

Bearer-аутентификация продолжает работать. Запрос авторизуется действительным Access JWT или действительным bearer-токеном, поэтому агентам, умеющим работать с заголовками, не нужны изменения.

Источник не обслуживает /.well-known/oauth-* — с включённым Managed OAuth Access является сервером авторизации и обслуживает обнаружение на границе.

Строгий режим (MCP_STRICT_ENV=1)

Подход для необслуживаемого развёртывания. Секреты должны приходить из окружения, сервер никогда не создаёт и не сохраняет учётные данные, и он завершается с кодом 1 и сообщением с указанием действий, а не запускается с неправильной конфигурацией. Он также отказывается от формы токена в пути URL, которая помещает учётные данные в журналы доступа прокси.

Это важно, потому что поиск файла .env намеренно имеет приоритет над process.env — настольный хост перезаписывает свой собственный файл конфигурации из памяти при выходе, поэтому файл должен побеждать там. На сервере этот приоритет обратный: случайный .env в рабочем каталоге молча перекрыл бы systemd-юнит. Строгий режим отключает поиск.

См. deploy/DEPLOY.md для полного рецепта: скрипт настройки VPS, укреплённый systemd-юнит, Cloudflare Tunnel и подключение к Claude.

Обновление с 3.x

Имена инструментов полностью другие — 4.x это переписывание, а не переименование. Всё, что содержит жёстко заданные имена инструментов 3.x (сохранённые промпты, инструкции агентов, скрипты), нужно обновить.

Соответствие в основном «многие к одному»:

Не перенесено: project_intelligence (восемь локальных аналитических отчётов) и reminders_create. Управление статусами *— создание, переименование, изменение порядка статусов — также отсутствует; meta читает статусы, но не изменяет их. Если вам нужно что-то из этого, используйте 3.x.

Запуск 3.x

3.x по-прежнему собирается и поставляется из этого репозитория:

npm run start:v3       # via the package script
node build/index.js    # the 3.x entry point directly

Укажите MCP-клиенту на build/index.js вместо build/v4/index.js, чтобы продолжать его использовать.

Эталонный systemd-юнит в deploy/ намеренно по-прежнему привязан к 3.x, потому что работающий сервис не должен менять мажорную версию из-за того, что значение по умолчанию пакета изменилось под ним. Перенесите его, указав ExecStart на build/v4/index.js и явно задав MCP_PROFILE.

Известные ограничения API ClickUp

Это не ошибки — в API действительно этого нет, и этот сервер сообщает об ограничении, а не делает вид, что обходит его.

• Задачи нельзя перемещать между списками. POST /list/{dest}/task/{id} возвращает 200 {} и ничего не делает без ClickApp «Tasks in Multiple Lists»; PUT с list_id молча игнорируется; /move возвращает 404. Путь перемещения в update считывает задачу обратно и завершается с ошибкой, а не сообщает о перемещении, которого не произошло.

• У вложений нет эндпоинта для списка — task считывает их из объекта задачи. Загрузка только через multipart, ограничение — 25 МБ.

• Документы нельзя переименовать или удалить, а страницы нельзя удалить.

• Определения пользовательских полей можно просматривать и создавать, но нельзя редактировать или удалять.

• Поля даты требуют Unix-миллисекунды; YYYY-MM-DD ClickUp для них отклоняет. due_date/start_date задачи принимают оба формата и здесь преобразуются.

• Названия статусов и тегов хранятся в нижнем регистре; сопоставление здесь везде без учёта регистра.

• Списки постоянно переопределяют статусы своего пространства, поэтому вопрос «какие статусы допустимы» решается для каждого списка отдельно. meta отвечает на него по каждому списку.

• ClickUp отвечает на недопустимое значение перечисления HTTP 500, поэтому перечисления проверяются на стороне клиента перед отправкой.

• Ограничение скорости — примерно 100 запросов/минуту на токен, общее для всего, что его использует. whoami сообщает текущий бюджет; сервер выдерживает темп, ориентируясь на заголовки x-ratelimit-*.

Приёмник вебхуков (опционально)

Обработка событий вебхуков ClickUp без внешней инфраструктуры:

WEBHOOK_PORT=3001 WEBHOOK_SECRET=your_secret node build/webhook-receiver/index.js

• Проверка HMAC-SHA256 по необработанному телу запроса; при настроенном секрете запросы без подписи отклоняются

• Структурированный разбор событий — тип, объект, операция, изменения, пользователь, метка времени

• Опциональная пересылка на callback-URL (WEBHOOK_FORWARD_URL)

• Чистый Node.js http, ноль дополнительных зависимостей

Разработка

npm install
npm run build
npm test          # 354 tests, mocked HTTP — no token needed
npm run smoke     # live CRUD walk (needs CLICKUP_API_TOKEN; creates and
                  # deletes its own sandbox in your workspace)

Заметки по архитектуре для 4.x — в src/v4/README.md; обоснование дизайна и измерения — в V4-PLAN.md.

Отладка исправления, которое «не сработало»

Вызовите whoami. Он сообщает версию и метку сборки запущенного билда. MCP-хосты запускают собственный процесс сервера при старте сессии и удерживают его, поэтому пересборка не доходит до уже запущенной сессии — если метка старше вашего изменения, перезапустите приложение-хост. Это объяснило несколько фантомных баг-репортов до появления этого инструмента.

Лицензия

MIT — см. LICENSE. Форк nsxdavid/clickup-mcp-server Дэвида Уотли.