Workel MCP Server

Официальный сервер Model Context Protocol для Workel — тонкий, не сохраняющий состояние клиент Workel Public API v1. Он предоставляет рабочее пространство Workel AI-агентам (Claude, OpenAI Agents SDK или любому другому клиенту, говорящему на MCP) в виде небольшого набора четко ограниченных инструментов. Все правила, которые действительно имеют значение — что этот ключ может видеть, что он может записывать, как быстро он может это записывать — живут в самом API Workel; этот пакет не обладает никакими полномочиями, которых у ключа уже нет. Запрос curl, сделанный с тем же ключом, может сделать ровно то же, что и этот сервер, и не больше.

Полные инструкции по настройке для каждого клиента (Claude Desktop, Claude Code, .mcp.json в рамках проекта и OpenAI Agents SDK) см. в документации разработчика Workel.

Используете Claude? Вероятно, этот пакет вам не нужен

Workel запускает хостируемый MCP-сервер. Добавьте его в Claude в разделе Settings → Connectors → Add custom connector:

https://mcp.workel.com/mcp

Вы входите в Workel, выбираете одно рабочее пространство и подключаетесь. Без установки, без файла конфигурации и без API-ключа — вы его не видите, и Claude тоже. Для авторизации требуется роль владельца или администратора в выбранном рабочем пространстве, и соединение проверяется заново при каждом запросе, поэтому потеря этой роли отключает его без необходимости кому-либо помнить об отзыве ключа.

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

Подключение более чем одного рабочего пространства

Одно соединение покрывает одно рабочее пространство, потому что учетные данные, лежащие в его основе, привязаны к этому рабочему пространству. Чтобы получить доступ ко второму, добавьте коннектор снова и выберите другое рабочее пространство — каждое соединение регистрируется отдельно, поэтому они сосуществуют, и каждое отображается под именем своего рабочего пространства (workel — Acme), а не как одинаковые записи, которые невозможно различить.

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

Related MCP server: Google Workspace MCP Server

Запуск самостоятельно

Этот пакет предназначен для случаев, которые не покрывает хостируемый сервер: Claude Code, CI-агенты, OpenAI Agents SDK — везде, где вы хотите запускать процесс самостоятельно и хранить учетные данные. Все, что описано ниже, относится именно к этому.

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

Создайте выделенный ключ только для чтения перед началом работы

Прежде чем направлять любого AI-клиента на этот сервер, перейдите в Workel → Settings → Developers и создайте новый API-ключ специально для этой цели — не используйте повторно ключ, который уже использует другая интеграция. Для создания ключа требуется роль владельца или администратора. Предоставьте ему только те области read:*, которые реально используются инструментами в этом выпуске (read:projects, read:tasks, read:members, read:events — см. Tools ниже); оставьте все области write:* неотмеченными, если вы сознательно не решили позволить агенту самостоятельно создавать и редактировать объекты в вашем рабочем пространстве. Используйте один ключ на машину или агента, назовите его так, чтобы потом помнить, для чего он предназначен, и если машина выводится из эксплуатации или клиент скомпрометирован, отзовите этот один ключ в Settings → Developers, а не ротируйте ключ, которым пользуются несколько инструментов — отзыв мгновенный и вступает в силу при следующем запросе.

Прежде чем касаться флагов, описанных ниже, стоит понять две вещи:

• WORKEL_ENABLE_WRITES — это локальный флаг согласия оператора, а не граница авторизации. Он может только сузить то, что предлагается уже ограниченному по областям ключу, но никогда не расширить — и поскольку он находится в файле конфигурации или переменной окружения, к которой AI-агент, выполняющий код, обычно имеет доступ на запись, агент, работающий на вашей машине, может сам переключить его обратно на true. Локальный флаг — это не то, что можно доверить недоверенному агенту оставить в покое. Собственные области ключа — предоставленные осознанно при создании и отзываемые в любой момент — являются настоящим шлюзом.

• Переопределение WORKEL_API_BASE_URL отправляет ваш ключ на другой хост. Каждый запрос, который делает этот сервер, несет ваш ключ в заголовке Authorization. Если WORKEL_API_BASE_URL когда-либо указывает на URL, которым вы не управляете, этот хост получает ваш ключ при каждом вызове. Этот клиент отказывается от переопределения через обычный http://, кроме localhost/127.0.0.1/[::1], именно по этой причине. Та же логика применима к реальному ключу, вставленному в любой файл: если он когда-либо попадет в git, ротация ключа — единственное реальное исправление — история git вечна. Более поздний коммит, удаляющий строку, не удаляет ее из истории репозитория, и любой, кто клонировал репозиторий в промежутке, все еще имеет старый ключ.

Установка

npx -y @workel/mcp@0.4.0

Зафиксируйте версию — 0.4.0 выше — это текущий выпуск этого пакета; проверьте npm view @workel/mcp version для последней версии перед фиксацией. Форма без фиксации ниже — только для удобства, подходит для разовой ручной попытки, но не для того, что конфигурация агента запускает без присмотра:

npx -y @workel/mcp

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

doctor

Запустите npx -y @workel/mcp@0.4.0 doctor в любой момент, когда ваш MCP-клиент сообщает только «серверу не удалось запуститься» без дополнительных деталей. Он выполняет ту же самую проверку запуска, которую выполняет сам сервер — загружает конфигурацию, затем проверяет GET /me — и выводит отчёт в виде обычного текста в stdout, вместо того чтобы пытаться говорить на протоколе MCP:

base URL: https://api.workel.com/api/public/v1
workspace: Acme Inc
key: ci-key
scopes: read:projects, read:tasks
2 tools would register: workel_whoami, workel_list_projects
write budget: 59/60 remaining this minute

doctor никогда не запускает транспорт и никогда не общается с вашим MCP-клиентом — это отдельная команда, которую вы запускаете из терминала, и она завершается с кодом 0 при успехе или 1 при любой ошибке (отсутствующий/недействительный WORKEL_API_KEY, недоступный API или ключ, отклонённый API). В отличие от однострочной сводки, которую сервер выводит в stderr при обычной загрузке (которая опускает базовый URL, когда он является значением по умолчанию), doctor всегда выводит фактический базовый URL — включая случай, когда он является значением по умолчанию — потому что запуск doctor — это именно тот момент, когда подменённый WORKEL_API_BASE_URL должен быть виден.

Инструменты

Этот релиз регистрирует следующие инструменты чтения. workel_whoami не требует никакой области и работает с любым действительным ключом; каждый другой инструмент регистрируется только тогда, когда области ключа (обнаруженные через проверку GET /me выше) включают указанную область. Инструменты списков возвращают 25 результатов за вызов по умолчанию (максимум 50 — этот клиент намеренно ограничивает ниже собственных 100 API, см. src/tools/conventions.ts) и разбивают на страницы через непрозрачную пару cursor / next_cursor.

Инструменты записи

Четыре, и они регистрируются только когда оба условия выполнены: ключ имеет соответствующий scope write:* и установлено WORKEL_ENABLE_WRITES=true. Ни одно из них по отдельности ничего не регистрирует, поэтому установка только для чтения их никогда не видит.

Ни один инструмент ничего не удаляет. workel_update_task аннотирован destructiveHint: true, поэтому клиент, который уважает аннотации, запрашивает подтверждение перед каждым вызовом; инструменты чтения аннотированы как read-only и работают без него.

Размещённый сервер на mcp.workel.com работает с включённой записью, поэтому все тринадцать инструментов доступны там.

Ограничения

replayed не доказывает уникальность. Каждая запись, которую сделали бы инструменты этого сервера, несёт Idempotency-Key, и хранилище идемпотентности Workel API (хранение 24 часа, привязано к вызывающему ключу) воспроизводит точно такой же ответ для повторной попытки с тем же ключом и тем же телом запроса — вторая попытка сообщает replayed: true, и ничего не создаётся и не изменяется второй раз.

replayed: false означает, что данная конкретная попытка действительно выполнилась — это не означает, что дубликата не существует где-либо ещё. В частности: ответ об ошибке никогда не кэшируется, поэтому повторная попытка после сбоя всегда выполняется по-настоящему; запись идемпотентности истекает через 24 часа, поэтому очень поздняя повторная попытка выполняется по-настоящему; и хранилище разделено по пространствам имён для каждого ключа API, поэтому одно и то же буквальное значение Idempotency-Key, отправленное под другим ключом, никогда не сталкивается с первым и никогда не защищает от дубликата, созданного первым. Если вызов инструмента явно не использует тот же ключ идемпотентности в двух попытках, каждая попытка является действительно независимой записью, насколько может определить сервер.