clickup-mcp

Сервер ClickUp MCP для Claude — предоставляет задачи, пространства, папки, списки и комментарии ClickUp как инструменты MCP.

Технологический стек: Python 3.12 + uv + FastMCP (Starlette/FastAPI)

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

# Install dependencies
cd D:\leo\mcp-server\clickup-mcp
uv sync

# Run in stdio mode (for Claude Desktop)
$env:CLICKUP_API_TOKEN="pk_xxxxx"
uv run clickup-mcp

Related MCP server: Clickup Universal MCP Server

Конфигурация

Скопируйте .env.example в .env и заполните свои значения:

Получите ваш API токен: ClickUp → Settings → Apps → API Token

Настройка Claude Desktop

Добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "clickup": {
      "command": "uv",
      "args": ["run", "--directory", "D:/leo/mcp-server/clickup-mcp", "clickup-mcp"],
      "env": {
        "CLICKUP_API_TOKEN": "pk_xxxxx"
      }
    }
  }
}

Режимы транспорта

stdio (Claude Desktop / CLI)

$env:CLICKUP_API_TOKEN="pk_xxxxx"
uv run clickup-mcp

HTTP — однотенантный

$env:CLICKUP_API_TOKEN="pk_xxxxx"
$env:MCP_TRANSPORT="http"
$env:MCP_HTTP_PORT="8080"
uv run clickup-mcp

HTTP — шлюз / мультитенантный

$env:MCP_TRANSPORT="http"
$env:AUTH_MODE="gateway"
uv run clickup-mcp
# Each request must include: X-Clickup-Token: pk_xxxxx

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

Поиск ClickUp user ID пользователя

Используйте clickup_list_members. В родном ответе ClickUp GET /team содержится полный список участников по каждой команде (teams[].members[].user.{id,username,email}), но clickup_get_workspaces удаляет эту информацию, чтобы ответ оставался компактным, поэтому это не то место, где следует искать людей. clickup_list_members читает тот же базовый эндпоинт и проецирует список участников в плоскую, специально созданную структуру (id/username/email/team_id/role), чтобы вызывающим не приходилось извлекать её из полного объекта рабочего пространства/команды самостоятельно. clickup_list_tasks_for_person использует внутри тот же базовый поиск для преобразования email -> user_id.

Известное ограничение: объект участника команды ClickUp не имеет надёжного поля «деактивирован ли этот участник» — clickup_list_members не возвращает поле active, поскольку за ним нет реальных данных (единственное поле status, присутствующее в исходном объекте, invited_by.status, описывает пригласившего, а не участника).

clickup_search_tasks уже возвращает status.type

Как и все остальные инструменты чтения здесь, clickup_search_tasks и clickup_get_task передают исходный объект задачи ClickUp без изменений — включая поле type объекта status (open / custom / closed / done), которое является единственным надёжным способом определить, считается ли статус с пользовательским названием завершённым. Для этого не потребовалось изменений кода; это уже было там. clickup_list_tasks_for_person явно выводит его как status_type для каждой возвращаемой задачи для удобства.

Как EOS Rocks представлены в этом рабочем пространстве ClickUp

Подтверждено 18.08.2026 при непосредственном просмотре полей реальной задачи Rock (не догадки): Rocks — это обычные задачи ClickUp, находящиеся в списке, буквально названном "Rocks" (обнаружено в пространстве "Company" > папка "EOS Traction"), каждая из которых имеет специальные пользовательские поля: Quarter (выпадающий список, "Q1 2024".."Q4 2026"), Rocks Status (On Hold / Off Track / On Track / Completed / Blocked / At Risk), Rock Type (Company / Individual / Departmental / Team Rock), Department и прогресс через Progress (вручную) или Progress % (автоматически, свёртка чеклистов). Это не ClickUp Goals API и не простой список задач без метаданных — это задачи плюс пользовательские поля.

clickup_list_rocks_for_org находит каждый список с именем "Rocks" (по имени, а не жёстко заданному ID, на случай если пространства/папки будут реорганизованы) во всех рабочих пространствах, видимых токену, читает эти поля и нормализует их:

• quarter: метка ClickUp "Q3 2026" преобразуется в 2026-Q3 (и обратно, для входного фильтра quarter).

• status: 6 исходных опций ClickUp отображаются в 5-значный контракт (on_track/off_track/done/missed/open) — см. комментарий _STATUS_MAP в rocks.py для точного отображения и объяснения, почему missed никогда не генерируется (в данных ClickUp нет ничего, что отличало бы «истекло время» от общего «отклонение»; выводить это из просроченной due_date было бы неподтверждённым бизнес-логическим предположением, поэтому здесь это не делается).

• measurable: для этого списка нет выделенного поля. Используется описание задачи; null, если и оно пустое (никогда не выдумывается).

• weekly_status: нигде не найден структурированный источник (ни пользовательское поле, ни что-то из комментариев) — всегда возвращается как []. Если организация начнёт отслеживать это в ClickUp каким-то другим способом, пересмотреть.

Вложения и изображения

REST API ClickUp не позволяет прикрепить файл напрямую к комментарию — только к задаче (POST /task/{task_id}/attachment, что оборачивает clickup_attach_task_file). Также нет эндпоинта для удаления/обновления вложения; повторная загрузка добавляет новое вложение, а не заменяет старое, а удаление требует использования веб- или десктопного приложения ClickUp. Подтверждено проверкой описаний инструментов официального MCP-сервера ClickUp — то же разделение (инструмент Create Task Comment без поддержки вложений и отдельный инструмент Attach File to Task).

Чтобы изображение отображалось встроенным внутри комментария, хитрость в следующем: сначала загрузите файл в задачу, затем укажите возвращённый URL из ответа файла, используя синтаксис Markdown для изображения в тексте комментария — средство рендеринга комментариев ClickUp встраивает его как настоящее изображение, а не просто ссылку. clickup_create_comment_with_image выполняет оба шага одним вызовом:

clickup_create_comment_with_image(task_id, file_content_base64, filename)
# internally:
#   1. POST /task/{task_id}/attachment  -> {"url": "...", ...}
#   2. POST /task/{task_id}/comment     comment_text = "![filename](url)"

Чтобы сделать это вручную (например, добавить другой текст вокруг изображения), вызовите два инструмента самостоятельно:

1. result = clickup_attach_task_file(task_id, file_content_base64, filename)
   -> result["url"] is the uploaded file's URL

2. clickup_create_task_comment(
     task_id,
     comment_text=f"![{filename}]({result['url']})"
   )

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

• Документация ClickUp API v2

• Создание вложения задачи