ClickUp MCP-сервер

Реализация сервера Model Context Protocol для интеграции ClickUp, позволяющая помощникам на базе искусственного интеллекта взаимодействовать с рабочими пространствами ClickUp.

Этот сервер работает через Stdio согласно спецификации MCP при вызове клиентом MCP.

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

Этот сервер использует ваш ClickUp Personal API Token для аутентификации.

1. Создайте персональный токен API: в настройках ClickUp перейдите в «Мои настройки» > «Приложения» и создайте токен.

2. Настройте свой клиент MCP (например, Claude for Desktop): установите требуемую переменную среды при настройке сервера для вашего клиента.

Пример фрагмента конфигурации для клиента MCP:

3. Перезапустите MCP-клиент.

При необходимости сервер будет автоматически загружен и запущен клиентом MCP.

Установка через Smithery

Чтобы автоматически установить ClickUp MCP Server для Claude Desktop через Smithery :

Переменные среды

Необходимый

• CLICKUP_PERSONAL_TOKEN : Ваш ClickUp Personal API Token. Это необходимо для аутентификации сервера с ClickUp API.

Необязательный

• LOG_LEVEL : Уровень ведения журнала для сервера. Поддерживает error , warn , info , debug . По умолчанию info .

• ENCRYPTION_KEY : Постоянный 32-байтовый шестнадцатеричный ключ. Система конфигурации ( src/config/app.config.ts ) загружает или генерирует этот ключ, а src/security.ts содержит функции шифрования/дешифрования. Однако в настоящее время этот механизм не используется для шифрования CLICKUP_PERSONAL_TOKEN в потоке аутентификации Personal API Token ClickUpService .

• PORT : Порт сервера. Не используется в режиме сервера Stdio MCP по умолчанию, но может быть важен, если явно добавлены транспорт HTTP или дополнительные функции HTTP (например, отдельная конечная точка проверки работоспособности). По умолчанию в конфигурации 3000 если считано.

Доступные инструменты

В настоящее время реализованы следующие инструменты MCP:

Управление задачами

• clickup_create_task : создать новую задачу в списке ClickUp.

  • Требуется: list_id , name .

  • Необязательно: description , status , priority , assignees , due_date , time_estimate , tags .

• clickup_update_task : обновить свойства существующей задачи.

  • Требуется: task_id .

  • Необязательно: любые записываемые свойства ClickUpTask .

Управление командой и списком

• clickup_get_teams : получение всех доступных команд (рабочие пространства в ClickUp API v2).

• clickup_get_lists : Получить все списки в определенной папке.

  • Требуется: folder_id .

Совет директоров

• clickup_create_board : создать новую доску в пространстве ClickUp.

  • Требуется: space_id , name .

Управление пространством

• clickup_get_spaces : извлекает все пространства для заданного рабочего пространства (команды).

  • Требуется: team_id (идентификатор рабочей области).

  • Необязательно: archived (логическое значение, по умолчанию false ).

• clickup_create_space : создает новое пространство внутри рабочего пространства.

  • Требуется: team_id (ID рабочей области), name .

  • Необязательно: multiple_assignees (логическое значение), features (объект с флагами функций, такими как due_dates , time_tracking и т. д.).

• clickup_get_space : Извлекает сведения о конкретном пространстве.

  • Требуется: space_id .

• clickup_update_space : Обновляет существующее пространство.

  • Требуется: space_id .

  • Необязательно: name , color , private , admin_can_manage , archived , features .

• clickup_delete_space : Удаляет пробел.

  • Требуется: space_id .

Управление папками

• clickup_get_folders : извлекает все папки в указанном пространстве.

  • Требуется: space_id .

  • Необязательно: archived (логическое значение, по умолчанию false ).

• clickup_create_folder : создает новую папку в пространстве.

  • Требуется: space_id , name .

• clickup_get_folder : Извлекает сведения о конкретной папке.

  • Требуется: folder_id .

• clickup_update_folder : Обновляет существующую папку.

  • Требуется: folder_id , name .

• clickup_delete_folder : Удаляет папку.

  • Требуется: folder_id .

Управление пользовательскими полями

• clickup_get_custom_fields : извлекает все доступные пользовательские поля для указанного списка.

  • Требуется: list_id .

• clickup_set_task_custom_field_value : Устанавливает значение настраиваемого поля для определенной задачи.

  • Требуется: task_id , field_id , value .

  • Необязательно: value_options (объект, например, { "time": true } для полей даты).

• clickup_remove_task_custom_field_value : удаляет/очищает значение настраиваемого поля из определенной задачи.

  • Требуется: task_id , field_id .

Управление документами

Примечание: API ClickUp для Docs (особенно v2, с некоторыми операциями, которые теперь используют v3) имеет ограничения. Контент в основном обрабатывается как Markdown. Расширенное форматирование или сложные вставки могут не поддерживаться полностью. Прямое удаление документов через API в настоящее время не поддерживается конечной точкой ClickUp V3 /docs; управляйте жизненным циклом Doc посредством архивации или манипулирования страницами.

• clickup_search_docs : Поиск документов в рабочей области (команда).

  • Требуется: workspace_id .

  • Необязательно: query (строка), include_archived (логическое значение).

• clickup_create_doc : Создает новый документ.

  • Требуется: workspace_id , name .

  • Необязательно: parent (объект с id и type ), visibility (строка: «private», «workspace», «public»), create_page (логическое значение).

• clickup_get_doc_pages : Извлекает список страниц в определенном документе.

  • Требуется: doc_id .

• clickup_create_doc_page : создает новую страницу в определенном документе.

  • Требуется: workspace_id , doc_id , name (заголовок страницы).

  • Необязательно: content (Markdown), orderindex (число, хотя API v3 может его не использовать), parent_page_id (строка), sub_title (строка), content_format (строка).

• clickup_get_doc_page_content : извлекает содержимое (Markdown) определенной страницы документа.

  • Требуется: workspace_id , doc_id , page_id .

  • Необязательно: content_format (строка).

• clickup_edit_doc_page_content : обновляет содержимое и/или заголовок определенной страницы документа.

  • Требуется: workspace_id , doc_id , page_id , content (Markdown).

  • Необязательно: title (строка, сопоставляется с API «name»), sub_title (строка), content_edit_mode (строка: «replace», «append», «prepend»), content_format (строка).

Посмотреть управление

• clickup_get_views : извлекает все представления для заданного родительского ресурса (команда, пространство, папка или список).

  • Требуется: parent_id (идентификатор родительского ресурса), parent_type (строка: «team», «space», «folder» или «list»).

• clickup_create_view : создает новое представление в команде, пространстве, папке или списке.

  • Требуется: parent_id , parent_type , name (строка: имя нового представления), type (строка: тип представления, например, «список», «доска», «календарь», «Гантт»).

  • Необязательно: grouping , divide , sorting , filters , columns , team_sidebar , settings (объекты, определяющие конфигурации представления).

• clickup_get_view_details : Извлекает сведения о конкретном представлении.

  • Требуется: view_id .

• clickup_update_view : Обновляет существующее представление.

  • Требуется: view_id .

  • Необязательно: name (строка), grouping , divide , sorting , filters , columns , team_sidebar , settings .

• clickup_delete_view : Удаляет представление.

  • Требуется: view_id .

• clickup_get_view_tasks : Извлекает задачи, относящиеся к определенному представлению.

  • Требуется: view_id .

  • Необязательно: page (номер: 0-индексированный номер страницы для нумерации страниц).

Разработка

1. Клонируйте репозиторий:

   git clone <repository_url> cd clickup-mcp-server

2. Установить зависимости:

   npm install

3. Создайте файл .env в корневом каталоге и добавьте свой CLICKUP_PERSONAL_TOKEN :

   CLICKUP_PERSONAL_TOKEN=your_actual_personal_api_token_here LOG_LEVEL=debug

4. Запуск в режиме разработки (Stdio): сервер будет прослушивать сообщения MCP на stdin/stdout.

   npm run dev

   Здесь для запуска src/index.ts используется ts-node-dev .

5. Сборка для производства:

   npm run build

   Это скомпилирует TypeScript в dist/ .

6. Проведите тесты:

   npm test

   Это запускает модульные тесты Jest, расположенные в src/__tests__ . Убедитесь, что у вас есть файл .env.test (см. src/__tests__/setup.ts ).

Тестирование с помощью MCP Inspector

Вы можете протестировать сервер локально с помощью MCP Inspector:

1. Убедитесь, что ваш CLICKUP_PERSONAL_TOKEN доступен. Вы можете:

   • Установите его в своей оболочке перед запуском инспектора.

   • Установите его в пользовательском интерфейсе MCP Inspector, если он предоставляет возможность для переменных среды сервера.

   • Поместите его в локальный файл .env (так как src/index.ts загружает dotenv ).

2. Запустите инспектор с сервером:

   npx @modelcontextprotocol/inspector node --loader ts-node/esm src/index.ts

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

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

• Аутентификация с использованием вашего ClickUp Personal API Token. Сохраняйте этот токен в безопасности и конфиденциальности. Относитесь к нему как к паролю.

• Сервер ожидает, что CLICKUP_PERSONAL_TOKEN будет предоставлен через переменную среды потребляющим клиентом MCP или средой разработки.

• Система конфигурации включает логику для ENCRYPTION_KEY , а src/security.ts имеет функции шифрования, но в настоящее время это не применяется к токену Personal API службой ClickUpService .

• Никакие конфиденциальные данные (например, сам токен) не регистрируются по умолчанию с LOG_LEVEL=info . Уровень отладки может регистрировать больше подробностей.

• Ограничение частоты вызовов API ClickUp осуществляется путем регистрации оставшихся запросов (см. ClickUpService ).

Поиск неисправностей

Общие проблемы

1. Ошибки аутентификации (401 из ClickUp API)

   • Убедитесь, что переменная среды CLICKUP_PERSONAL_TOKEN установлена правильно и доступна серверному процессу.

   • Убедитесь, что токен действителен и не отозван в настройках ClickUp.

   • Проверьте журналы сервера на наличие сообщений от ClickUpService , касающихся аутентификации.

2. Ограничение скорости с помощью ClickUp API

   • Сервер регистрирует информацию об ограничении скорости из ответов API ClickUp.

   • Если ограничения скорости достигаются часто, это указывает на высокую загрузку. Сам сервер не реализует очередность или сложную отсрочку, помимо того, что axios может делать по умолчанию.

3. Сервер не запускается / Проблемы с подключением MCP Inspector

   • Убедитесь, что CLICKUP_PERSONAL_TOKEN установлен.

   • При использовании npm run dev проверьте наличие ошибок TypeScript или ts-node-dev в консоли.

   • При использовании MCP Inspector с node --loader ts-node/esm src/index.ts убедитесь, что зависимости ts-node и проекта установлены правильно.

   • Проверьте наличие ошибок консоли из src/index.ts или ClickUpService .

Получение журналов сервера

• При запуске через npm run dev или npm start логи отправляются в консоль.

• Если запущен клиент MCP (например, Claude for Desktop), журналы обычно управляются этим клиентом. Для Claude for Desktop журналы часто можно найти по адресу:

  • Windows: %USERPROFILE%\AppData\Local\Claude\Logs\mcp\<server_name_and_id>\<process_id>.log (путь может немного отличаться)

  • macOS: ~/Library/Logs/Claude/mcp/<server_name_and_id>\<process_id>.log (путь может немного отличаться)

Поддерживать

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

Лицензия

Лицензия MIT — подробности см. в файле LICENSE