Claude MCP x Google Docs

Лучший сервер Google Docs MCP

Подключите Claude Desktop (или другие клиенты MCP) к своим Google Docs!

🔥 Ознакомьтесь с 10 мощными задачами, которые вы можете выполнить с помощью этого улучшенного сервера!

Этот улучшенный сервер использует Model Context Protocol (MCP) и библиотеку fastmcp для предоставления комплексных инструментов для чтения, записи, форматирования и структурирования документов Google. Он действует как мощный мост, позволяя помощникам ИИ, таким как Клод, взаимодействовать с вашими документами программно с помощью расширенных возможностей.

Функции:

Доступ к документам

• Чтение документов: чтение контента с помощью readGoogleDoc (обычный текст, структура JSON или разметка)
• Добавить к документам: добавление текста в документы с помощью appendToGoogleDoc
• Вставить текст: поместите текст в определенные позиции с помощью insertText
• Удалить содержимое: удалить содержимое из документа с помощью deleteRange

Форматирование и стилизация

• Форматирование текста: применяйте расширенные стили с помощью applyTextStyle (жирный шрифт, курсив, цвета и т. д.)
• Форматирование абзаца: управляйте макетом абзаца с помощью applyParagraphStyle (выравнивание, интервалы и т. д.)
• Найти и форматировать: форматирование по текстовому содержимому с помощью formatMatchingText (поддержка устаревших версий)

Структура документа

• Таблицы: Создание таблиц с помощью insertTable
• Разрывы страниц: вставьте разрывы страниц с помощью insertPageBreak
• Экспериментальные функции: инструменты, такие как fixListFormatting для автоматического определения списков

Интеграция

• Аутентификация Google: безопасная аутентификация OAuth 2.0
• Совместимость с MCP: разработан для использования с Claude и другими клиентами MCP

Предпосылки

Прежде чем начать, убедитесь, что у вас есть:

1. Node.js и npm: Последняя версия Node.js (включая npm), установленная на вашем компьютере. Вы можете загрузить ее с nodejs.org . (Рекомендуется версия 18 или выше).
2. Git: Требуется для клонирования этого репозитория. ( Загрузить Git ).
3. Учетная запись Google: учетная запись, которая владеет или имеет доступ к Документам Google, с которыми вы хотите взаимодействовать.
4. Знакомство с командной строкой: базовые навыки использования терминала или командной строки (например, Терминала в macOS/Linux или Командной строки/PowerShell в Windows).
5. Claude Desktop (необязательно): если ваша цель — подключить этот сервер к Claude, вам потребуется установить приложение Claude Desktop.

Инструкции по установке

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

Шаг 1: Проект Google Cloud и учетные данные (важная часть!)

Этому серверу нужно разрешение на общение с API Google от вашего имени. Вы создадите специальные «ключи» (учетные данные), которые будет использовать только ваш сервер.

1. Перейдите в Google Cloud Console: Откройте веб-браузер и перейдите в Google Cloud Console . Возможно, вам потребуется войти в систему с помощью своей учетной записи Google.
2. Создайте или выберите проект:
   • Если у вас нет проекта, щелкните раскрывающийся список проектов вверху и выберите «НОВЫЙ ПРОЕКТ». Дайте ему имя (например, «Мой сервер MCP Docs») и щелкните «СОЗДАТЬ».
   • Если у вас есть существующие проекты, вы можете выбрать один или создать новый.
3. Включить API: вам необходимо включить определенные службы Google, которые использует этот сервер.
   • В строке поиска вверху введите «API и службы» и выберите «Библиотека».
   • Найдите " Google Docs API " и нажмите на него. Затем нажмите кнопку " ВКЛЮЧИТЬ ".
   • Найдите " Google Drive API " и нажмите на него. Затем нажмите кнопку " ENABLE " (это часто требуется для поиска файлов или разрешений).
4. Настройка экрана согласия OAuth: этот экран сообщает пользователям (обычно только вам), на какие разрешения запрашивает ваше приложение.
   • В левом меню выберите «API и службы» -> « Экран согласия OAuth ».
   • Выберите тип пользователя: выберите « Внешний » и нажмите «СОЗДАТЬ».
   • Заполните информацию о приложении:
     • Имя приложения: дайте ему имя, которое увидят пользователи (например, «Claude Docs MCP Access»).
     • Электронная почта службы поддержки пользователей: выберите свой адрес электронной почты.
     • Контактная информация разработчика: Введите свой адрес электронной почты.
   • Нажмите « СОХРАНИТЬ И ПРОДОЛЖИТЬ ».
   • Области: Нажмите « ДОБАВИТЬ ИЛИ УДАЛИТЬ ОБЛАСТИ ». Найдите и добавьте следующие области:
     • https://www.googleapis.com/auth/documents (позволяет читать/писать документы)
     • https://www.googleapis.com/auth/drive.file (разрешает доступ к определенным файлам, открытым/созданным приложением)
     • Нажмите « ОБНОВИТЬ ».
   • Нажмите « СОХРАНИТЬ И ПРОДОЛЖИТЬ ».
   • Тестовые пользователи: Нажмите « ДОБАВИТЬ ПОЛЬЗОВАТЕЛЕЙ ». Введите тот же адрес электронной почты Google, с которым вы вошли в систему. Нажмите « ДОБАВИТЬ ». Это позволит вам использовать приложение, пока оно находится в режиме «тестирования».
   • Нажмите « СОХРАНИТЬ И ПРОДОЛЖИТЬ ». Просмотрите сводку и нажмите « НАЗАД НА ПАНЕЛЬ УПРАВЛЕНИЯ ».
5. Создайте учетные данные (ключи!):
   • В левом меню нажмите «API и службы» -> « Учетные данные ».
   • Нажмите « + СОЗДАТЬ УЧЕТНЫЕ ДАННЫЕ » вверху и выберите « Идентификатор клиента OAuth ».
   • Тип приложения: выберите « Приложение для ПК » из раскрывающегося списка.
   • Имя: Дайте ему имя (например, «MCP Docs Desktop Client»).
   • Нажмите « СОЗДАТЬ ».
6. ⬇️ СКАЧАТЬ ФАЙЛ УЧЕТНЫХ ДАННЫХ: Появится окно с вашим идентификатором клиента. Нажмите кнопку « СКАЧАТЬ JSON ».
   • Сохраните этот файл. Скорее всего, он будет называться как-то вроде client_secret_....json .
   • ВАЖНО: Переименуйте загруженный файл в credentials.json .
7. ⚠️ ПРЕДУПРЕЖДЕНИЕ О БЕЗОПАСНОСТИ: Относитесь к этому файлу credentials.json как к паролю! Не делитесь им публично и никогда не публикуйте его на GitHub. Любой, у кого есть этот файл, может потенциально выдавать себя за ваше приложение (хотя для доступа к данным ему все равно потребуется согласие пользователя).

Шаг 2: Получите код сервера

1. Клонируйте репозиторий: Откройте терминал/командную строку и выполните:
   git clone https://github.com/a-bonus/google-docs-mcp.git mcp-googledocs-server
2. Перейдите в каталог:
   cd mcp-googledocs-server
3. Поместите учетные данные: переместите или скопируйте файл credentials.json , который вы скачали и переименовали (из шага 1.6), непосредственно в эту папку mcp-googledocs-server .

Шаг 3: Установка зависимостей

Вашему серверу необходимы некоторые вспомогательные библиотеки, указанные в файле package.json .

1. В терминале (убедитесь, что вы находитесь в каталоге mcp-googledocs-server ) выполните:
   npm install
   Это позволит загрузить и установить все необходимые пакеты в папку node_modules .

Шаг 4: Создание кода сервера

Сервер написан на TypeScript ( .ts ), но нам необходимо скомпилировать его в JavaScript ( .js ), который Node.js сможет запустить напрямую.

1. В терминале выполните:
   npm run build
   При этом используется компилятор TypeScript ( tsc ) для создания папки dist , содержащей скомпилированные файлы JavaScript.

Шаг 5: Первый запуск и авторизация Google (только один раз)

Теперь вам нужно запустить сервер один раз вручную, чтобы предоставить ему разрешение на доступ к данным вашего аккаунта Google. Это создаст файл token.json , который сохранит ваше разрешение.

1. В терминале запустите скомпилированный сервер с помощью node :
   node ./dist/server.js
2. Посмотрите на терминал: скрипт выведет:
   • Сообщения о состоянии (например, «Попытка авторизации...»).
   • Сообщение «Авторизуйте это приложение, посетив этот URL-адрес:», за которым следует длинный URL-адрес https://accounts.google.com/...
3. Авторизация в браузере:
   • Скопируйте весь длинный URL-адрес из терминала.
   • Вставьте URL-адрес в адресную строку веб-браузера и нажмите Enter.
   • Войдите в систему, используя ту же учетную запись Google, которую вы добавили в качестве тестового пользователя на шаге 1.4.
   • Google покажет экран с запросом разрешения для вашего приложения («Claude Docs MCP Access» или аналогичного) на доступ к Google Docs/Drive. Просмотрите и нажмите « Разрешить » или « Предоставить ».
4. Получите код авторизации:
   • После нажатия кнопки «Разрешить» ваш браузер, скорее всего, попытается перенаправить на http://localhost и выдаст ошибку «Этот сайт недоступен» . ЭТО НОРМАЛЬНО!
   • Внимательно посмотрите на URL в адресной строке браузера. Он будет выглядеть как http://localhost/?code=4/0Axxxxxxxxxxxxxx&scope=...
   • Скопируйте длинную строку символов между code= и частью &scope . Это ваш одноразовый код авторизации.
5. Вставьте код в терминал: Вернитесь в терминал, где вас ждет скрипт («Введите код с этой страницы здесь:»). Вставьте код, который вы только что скопировали.
6. Нажмите Enter.
7. Успех! Скрипт должен вывести:
   • «Аутентификация прошла успешно!»
   • «Токен сохранен в .../token.json»
   • Затем он завершит запуск и, скорее всего, выведет сообщение «Ожидание подключения клиента MCP через stdio...» или что-то подобное, а затем завершит работу (или вы можете нажать Ctrl+C , чтобы остановить его).
8. ✅ Проверка: теперь вы должны увидеть новый файл с именем token.json в папке mcp-googledocs-server .
9. ⚠️ ПРЕДУПРЕЖДЕНИЕ О БЕЗОПАСНОСТИ: Этот файл token.json содержит ключ, который позволяет серверу получать доступ к вашей учетной записи Google без повторного запроса. Защитите его как пароль. Не фиксируйте его на GitHub. Включенный файл .gitignore должен автоматически предотвратить это.

Шаг 6: Настройка Claude Desktop (необязательно)

Если вы хотите использовать этот сервер с Claude Desktop, вам нужно указать Claude, как его запустить.

1. Найдите абсолютный путь: вам нужен полный путь к коду сервера.
   • В терминале убедитесь, что вы все еще находитесь в каталоге mcp-googledocs-server .
   • Выполните команду pwd (в macOS/Linux) или cd (в Windows просто отображает путь).
   • Скопируйте полный путь (например, /Users/yourname/projects/mcp-googledocs-server или C:\Users\yourname\projects\mcp-googledocs-server ).
2. Найдите mcp_config.json : Найдите файл конфигурации Клода:
   • macOS: ~/Library/Application Support/Claude/mcp_config.json (Возможно, вам придется использовать меню Finder «Перейти» -> «Перейти к папке...» и вставить ~/Library/Application Support/Claude/ )
   • Windows: %APPDATA%\Claude\mcp_config.json (вставьте %APPDATA%\Claude в адресную строку Проводника)
   • Linux: ~/.config/Claude/mcp_config.json
   • Если папка Claude или файл mcp_config.json отсутствуют, создайте их.
3. Редактировать mcp_config.json : Откройте файл в текстовом редакторе. Добавьте или измените раздел mcpServers следующим образом, заменив /PATH/TO/YOUR/CLONED/REPO фактическим абсолютным путем, который вы скопировали на шаге 6.1 :
   { "mcpServers": { "google-docs-mcp": { "command": "node", "args": [ "/PATH/TO/YOUR/CLONED/REPO/mcp-googledocs-server/dist/server.js" ], "env": {} } // Add commas here if you have other servers defined } // Other Claude settings might be here }
   • Убедитесь, что путь в "args" правильный и абсолютный!
   • Если файл уже существовал, аккуратно объедините эту запись с существующим объектом mcpServers . Убедитесь, что JSON действителен (проверьте запятые!).
4. Сохраните mcp_config.json .
5. Перезапустите Claude Desktop: полностью закройте Claude и откройте его снова.

Использование с Claude Desktop

После настройки вы сможете использовать инструменты в чатах с Клодом:

• «Используйте сервер google-docs-mcp для чтения документа с идентификатором YOUR_GOOGLE_DOC_ID ».
• «Можете ли вы получить содержимое документа Google YOUR_GOOGLE_DOC_ID ?»
• «Добавьте «Это было добавлено Клодом!» к документу YOUR_GOOGLE_DOC_ID с помощью инструмента google-docs-mcp ».

Примеры расширенного использования:

• Стилизация текста : «Используйте applyTextStyle , чтобы сделать текст «Важный раздел» жирным и красным (#FF0000) в документе YOUR_GOOGLE_DOC_ID ».
• Стиль абзаца : «Используйте applyParagraphStyle для выравнивания по центру абзаца, содержащего «Заголовок здесь» в документе YOUR_GOOGLE_DOC_ID ».
• Создание таблицы : «Вставьте таблицу 3x4 в индекс 500 в документ YOUR_GOOGLE_DOC_ID с помощью инструмента insertTable ».
• Устаревшее форматирование : «Используйте formatMatchingText , чтобы найти второй экземпляр «Project Alpha» и сделать его синим (#0000FF) в документе YOUR_GOOGLE_DOC_ID ».

Не забудьте заменить YOUR_GOOGLE_DOC_ID фактическим идентификатором из URL-адреса Google Doc (длинная строка между /d/ и /edit ).

Claude автоматически запустит ваш сервер в фоновом режиме, когда это необходимо, используя указанную вами команду. Вам больше не нужно запускать node ./dist/server.js вручную.

Безопасность и хранение токенов

• .gitignore : Этот репозиторий включает файл .gitignore , который должен предотвратить случайную фиксацию ваших конфиденциальных файлов credentials.json и token.json . Не удаляйте эти строки из .gitignore .
• Хранилище токенов: этот сервер хранит токен авторизации Google ( token.json ) непосредственно в папке проекта для простоты настройки. В производственных или более чувствительных к безопасности средах рассмотрите возможность более безопасного хранения этого токена, например, с помощью системных цепочек ключей, зашифрованных файлов или выделенных служб управления секретами.

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

• Клод показывает «Ошибка» или «Не удалось прикрепить»:
  • Еще раз проверьте абсолютный путь в mcp_config.json .
  • Убедитесь, что вы успешно выполнили npm run build и папка dist существует.
  • Попробуйте вручную запустить команду из mcp_config.json в терминале: node /PATH/TO/YOUR/CLONED/REPO/mcp-googledocs-server/dist/server.js . Посмотрите на любые выведенные ошибки.
  • Проверьте логи Claude Desktop (см. официальное руководство по отладке MCP).
  • Убедитесь, что все сообщения о состоянии console.log в коде сервера были изменены на console.error .
• Ошибки авторизации Google:
  • Убедитесь, что вы включили правильные API (Docs, Drive).
  • Убедитесь, что вы добавили свой адрес электронной почты в качестве тестового пользователя на экране согласия OAuth.
  • Убедитесь, что файл credentials.json правильно размещен в корне проекта.

Лицензия

Этот проект лицензирован по лицензии MIT — подробности см. в файле LICENSE . (Примечание: вам следует добавить файл LICENSE , содержащий текст лицензии MIT, в свой репозиторий).