apps-script-mcp-server

MCP сервер, который позволяет Claude читать и отправлять код Google Apps Script (.gs, .html, appsscript.json) напрямую в проект скрипта — больше не нужно вручную копировать код в редактор Apps Script.

Создан для системы эпиднадзора за заболеваниями Kwara (панель KWARAB), но работает с любым проектом Apps Script, к которому у вас есть доступ на редактирование.

Что он умеет

Важное ограничение, которое нужно знать заранее: отправка кода с помощью apps_script_update_file / apps_script_update_content обновляет редактируемый проект — так же, как если бы вы вводили текст в редакторе скриптов и сохраняли. Это не обновляет автоматически ничего, что уже развёрнуто (например, URL работающего веб-приложения или триггеры, привязанные к конкретной развёрнутой версии). Чтобы опубликовать изменения, создайте версию (apps_script_create_version), а затем выполните повторное развёртывание из редактора Apps Script — этот сервер намеренно не затрагивает публикацию развёртываний, поскольку это более ответственное действие, которое стоит выполнять вручную первые несколько раз.

1. Одноразовая настройка Google Cloud (сделайте это сначала)

Вам понадобится проект Google Cloud с включённым API Apps Script и OAuth-клиентом. Это займёт около 5 минут.

1. Создайте или выберите проект Google Cloud Перейдите по ссылке https://console.cloud.google.com/projectcreate и создайте проект (любое название подойдёт — например, «kwarab-apps-script-mcp»). Если у вас уже есть проект GCP, который вы используете для других задач Kwara/Ekiti, вы можете использовать его повторно.

2. Включите API Apps Script в проекте Перейдите по ссылке https://console.cloud.google.com/apis/library/script.googleapis.com, выберите свой проект и нажмите Включить.

3. Настройте экран согласия OAuth Перейдите по ссылке https://console.cloud.google.com/apis/credentials/consent

   • Тип пользователя: Внешний (если у вас нет организации Google Workspace, тогда подойдёт «Внутренний»)

   • Заполните название приложения (например, «Apps Script MCP»), свой email как контакт для поддержки

   • Области: здесь можно пропустить добавление областей — сервер запрашивает их напрямую

   • Тестовые пользователи: добавьте свой собственный email учётной записи Google (требуется, пока приложение находится в статусе «Тестирование», что подходит для личного/внутреннего использования)

4. Создайте OAuth-клиент Перейдите по ссылке https://console.cloud.google.com/apis/credentials

   • Нажмите Создать учётные данные → ID клиента OAuth

   • Тип приложения: Десктопное приложение

   • Назовите его как угодно (например, «Apps Script MCP Desktop»)

   • Нажмите Создать, затем Скачать JSON

5. Сохраните загруженный файл как credentials.json в корневой папке этого проекта (в той же папке, что и этот README). Не сохраняйте этот файл в системе контроля версий и не делитесь им — он идентифицирует ваш OAuth-клиент (не вашу личную учётную запись, но всё равно держите его в тайне).

6. Включите API Apps Script для своей учётной записи Google Это отдельный шаг от шага 2 (там API включается для проекта; здесь — для учётной записи Google, которая владеет/редактирует скрипт). Перейдите по ссылке https://script.google.com/home/usersettings и включите «API Google Apps Script».

2. Установка и авторизация

npm install
npm run build
npm run authorize

npm run authorize открывает ваш браузер, просит войти в учётную запись Google, у которой есть доступ к проекту Apps Script для эпиднадзора за заболеваниями Kwara, и запрашивает разрешение доступа. После одобрения он сохраняет токен обновления в token.json в этой папке — вам нужно сделать это только один раз (повторно запустите, если вы когда-либо отзовёте доступ или смените учётную запись Google).

Если ничего не открывается автоматически: терминал выведет URL — скопируйте и вставьте его в любой браузер, одобрите, и вас перенаправят обратно на localhost, где скрипт ожидает; терминал подтвердит успех.

3. Подключение к Claude

Вариант A: Локальный (stdio) — Claude Code / Claude Desktop

Добавьте в свою конфигурацию MCP (например, claude_desktop_config.json или настройки MCP в Claude Code):

{
  "mcpServers": {
    "apps-script": {
      "command": "node",
      "args": ["/absolute/path/to/apps-script-mcp-server/dist/index.js"]
    }
  }
}

Перезапустите Claude Desktop / Claude Code после добавления. Вы должны увидеть apps-script в списке подключённых MCP серверов с доступными инструментами, такими как apps_script_update_file.

Вариант B: Удалённый (HTTP), например, размещённый на Render

Сервер также работает как отдельный HTTP-сервис — установите TRANSPORT=http. Это то, что render.yaml в этом репозитории настраивает автоматически. См. раздел Развёртывание на Render ниже.

Удалённый сервер доступен всем, у кого есть его URL, поэтому каждый запрос к /mcp должен содержать токен-носитель, соответствующий переменной окружения MCP_SERVER_TOKEN, которую вы установили:

Authorization: Bearer <your MCP_SERVER_TOKEN value>

В настройках удалённого MCP-соединителя Claude добавьте URL сервера (https://<your-service>.onrender.com/mcp) и установите этот заголовок. /healthz намеренно не требует аутентификации, чтобы проверки работоспособности Render могли до него добраться.

Развёртывание на Render

Этот репозиторий включает шаблон render.yaml, поэтому Render может создать сервис с предварительно заполненными настройками.

1. В панели управления Render: New → Blueprint, подключите свою учётную запись GitHub, если ещё не сделали этого, и выберите этот репозиторий. Render прочитает render.yaml.

2. Render запросит у вас переменные окружения, отмеченные как sync: false:

   • MCP_SERVER_TOKEN — придумайте длинную случайную строку (например, openssl rand -hex 32). Это то, что Claude должен отправлять как токен-носитель.

   • GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET, GOOGLE_OAUTH_REFRESH_TOKEN — сгенерируйте их локально сначала (шаги 1–2 выше, включая npm run authorize), затем откройте полученный token.json и скопируйте client_id, client_secret и refresh_token в поля переменных окружения Render. Render никогда не получает браузер, поэтому этот путь с безголовыми учётными данными заменяет локальный шаг npm run authorize.

3. Разверните. После запуска конечная точка MCP будет https://<your-service>.onrender.com/mcp.

4. На бесплатном тарифе Render выключает сервис после бездействия — первый запрос после простоя будет медленным (холодный старт), пока сервис снова запускается.

4. Использование

Вам понадобится ID скрипта проекта Apps Script для эпиднадзора за заболеваниями Kwara. Найдите его, открыв проект по ссылке https://script.google.com и скопировав ID из URL:

https://script.google.com/home/projects/<THIS_IS_THE_SCRIPT_ID>/edit

(Если скрипт Apps Script привязан к Google Таблице KWARAB, а не является самостоятельным, откройте таблицу → Расширения → Apps Script, чтобы попасть в тот же редактор и URL.)

Затем в беседе с Claude, к которой подключён этот MCP сервер, вы можете говорить что-то вроде:

• «Покажи мне текущий Code.gs в скрипте <scriptId>»

• «Обнови функцию sendAlertEmail в Code.gs, чтобы она также копировала супервизора DSNO»

• «Отправь этот новый файл Utils.gs с такими вспомогательными функциями: ...»

• «Создай новую версию с названием «Добавить логику авто-составления AFP EPID»»

Замечания по безопасности

• credentials.json и token.json предоставляют доступ к проектам Apps Script, которые вы можете редактировать. Храните их вне системы контроля версий (включён файл .gitignore) и не делитесь ими.

• Запрашиваемые области OAuth (script.projects, script.deployments) не включают доступ к Gmail, Таблицам или Диску, кроме необходимого для чтения/записи содержимого проекта скрипта и просмотра развёртываний.

• Чтобы отозвать доступ в любое время: https://myaccount.google.com/permissions → найдите имя OAuth-клиента, которое вы указали в шаге 4 выше → Удалить доступ. После этого удалите token.json.

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