{"_id":"@a1-x-tech/mcp-google-docs","name":"@a1-x-tech/mcp-google-docs","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@a1-x-tech/mcp-google-docs","version":"0.1.0","description":"MCP server for the Google Docs API — read documents as text, structure or Markdown, edit text by ranges, style, tables, images, comments and export. For Claude, Cursor, Codex and other AI clients.","mcpName":"io.github.A1-x-Tech/mcp-google-docs","type":"module","bin":{"mcp-google-docs":"dist/index.js"},"engines":{"node":">=20"},"publishConfig":{"access":"public"},"scripts":{"build":"rm -rf dist && tsc","start":"node dist/index.js","dev":"tsx watch src/index.ts","typecheck":"tsc -p tsconfig.check.json","smoke":"node --import tsx src/smoke.ts","test":"npm run test:src && npm run test:dist","test:src":"node --import tsx --test $(find src -name '*.test.ts')","test:dist":"npm run build && node --test test/dist-smoke.test.js","prepare":"npm run build","prepublishOnly":"npm run typecheck && npm test"},"keywords":["mcp","model-context-protocol","google","google-docs","docs","documents","markdown","claude","cursor","codex"],"license":"MIT","author":{"name":"gistrec","email":"gistrec@gmail.com"},"repository":{"type":"git","url":"git+https://github.com/A1-x-Tech/mcp-google-docs.git"},"homepage":"https://github.com/A1-x-Tech/mcp-google-docs#readme","bugs":{"url":"https://github.com/A1-x-Tech/mcp-google-docs/issues"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","zod":"^3.25.0"},"devDependencies":{"@types/node":"^25.9.3","tsx":"^4.22.4","typescript":"^5.7.0"},"gitHead":"25fc262ddad2121bf39902e9c1f9af1491d57169","_id":"@a1-x-tech/mcp-google-docs@0.1.0","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-eHqrIhrPyX/30e7Lx+whkNPmNkDKX1aXORXFS3TnRTDku4k1Nme/jYeSleJ4AblB2VCgWg4zNFIxL+j8SRudBA==","shasum":"9c868ac7e9fc27fe14d15ac026eed1da5b4e2f0b","tarball":"https://registry.npmjs.org/@a1-x-tech/mcp-google-docs/-/mcp-google-docs-0.1.0.tgz","fileCount":19,"unpackedSize":139304,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEMCHz+dacGEdRwkIqN+ohAneqg5CS0/zbJXnpisoO/VI5kCIFXyPUIpHbkvMj/LZqdtbEl/HCdJLhNTYoiWIPZnR4A0"}]},"_npmUser":{"name":"gistrec","email":"gistrec@gmail.com"},"directories":{},"maintainers":[{"name":"gistrec","email":"gistrec@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-google-docs_0.1.0_1788054560164_0.31505184175467016"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-30T01:49:20.054Z","0.1.0":"2026-08-30T01:49:20.308Z","modified":"2026-08-30T01:49:20.743Z"},"maintainers":[{"name":"gistrec","email":"gistrec@gmail.com"}],"description":"MCP server for the Google Docs API — read documents as text, structure or Markdown, edit text by ranges, style, tables, images, comments and export. For Claude, Cursor, Codex and other AI clients.","homepage":"https://github.com/A1-x-Tech/mcp-google-docs#readme","keywords":["mcp","model-context-protocol","google","google-docs","docs","documents","markdown","claude","cursor","codex"],"repository":{"type":"git","url":"git+https://github.com/A1-x-Tech/mcp-google-docs.git"},"author":{"name":"gistrec","email":"gistrec@gmail.com"},"bugs":{"url":"https://github.com/A1-x-Tech/mcp-google-docs/issues"},"license":"MIT","readme":"# <img src=\"./assets/a1-logo.svg\" alt=\"A1\" width=\"40\"> Google Docs MCP\n\n[English](./README.md) | **Русский**\n\n[![npm](https://img.shields.io/npm/v/%40a1-x-tech%2Fmcp-google-docs)](https://www.npmjs.com/package/@a1-x-tech/mcp-google-docs)\n[![CI](https://github.com/A1-x-Tech/mcp-google-docs/actions/workflows/ci.yml/badge.svg)](https://github.com/A1-x-Tech/mcp-google-docs/actions/workflows/ci.yml)\n[![Glama](https://glama.ai/mcp/servers/A1-x-Tech/mcp-google-docs/badges/score.svg)](https://glama.ai/mcp/servers/A1-x-Tech/mcp-google-docs)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n\n**A1 Google Docs MCP** позволяет AI-приложению читать и редактировать Google Docs на естественном языке. Можно прочитать документ как текст или Markdown, точечно изменить нужный фрагмент, оформить заголовки, списки и таблицы, разобрать ветки комментариев и выгрузить результат в PDF или DOCX.\n\nСервер работает с Google Docs API через ваш Google-аккаунт. Он правит текст по точным диапазонам индексов, а не наугад, и явно показывает ограничения Docs API, а не создаёт впечатление, что с документом можно сделать всё.\n\n- **21 инструмент.** Чтение документа как текста, структуры или Markdown, правка точных диапазонов, стили символов и абзацев, списки, таблицы, разрывы, изображения, ветки комментариев и экспорт в PDF, DOCX и другие форматы.\n- **Точечные правки.** Изменения адресуются точными диапазонами индексов, и сервер подталкивает ассистента перечитывать документ перед каждой правкой, потому что каждое изменение сдвигает индексы после него.\n- **Markdown в обе стороны.** Документ можно создать из Markdown или выгрузить в Markdown, PDF, DOCX и другие форматы; замена всего документа из Markdown — отдельный, явно разрушительный шаг.\n- **Без скрытого доступа к Drive.** Экспорт, конвертация Markdown и комментарии внутри используют эндпоинты Drive, но отдельного инструмента общего назначения для Drive у сервера нет.\n\nНачните с запроса, который только читает данные:\n\n> Прочитай документ с планом запуска и кратко перескажи открытые ветки комментариев.\n\n[Подключить сервер](#быстрый-старт) · [Посмотреть сценарии](#что-можно-поручить) · [Открыть техническую документацию](#техническая-документация)\n\n---\n\n## Увидеть работу за минуту\n\n> **Вы:** Покажи текст и комментарии документа с планом запуска.\n>\n> **Ассистент:** Читает документ как компактные текстовые блоки и перечисляет ветки комментариев. Ничего не меняется.\n>\n> **Вы:** Перепиши абзац «Сроки»: бета начинается 3 марта.\n>\n> **Ассистент:** Показывает точный диапазон, который заменит, и предлагаемый текст, затем запрашивает подтверждение перед правкой.\n>\n> **Вы:** Подтверждаю.\n>\n> **Ассистент:** Заменяет только этот диапазон. Остальной текст, форматирование и комментарии остаются как были.\n\n## Содержание\n\n- [Быстрый старт](#быстрый-старт)\n- [Что можно поручить](#что-можно-поручить)\n- [Как меняется документ](#как-меняется-документ)\n- [Что может измениться](#что-может-измениться)\n- [Как получить доступ](#как-получить-доступ)\n- [Конфигурация](#конфигурация)\n- [Данные, лимиты и работа в фоне](#данные-лимиты-и-работа-в-фоне)\n- [Техническая документация](#техническая-документация)\n- [Поддержка](#поддержка)\n\n## Быстрый старт\n\nНужны Node.js 20+, Google-аккаунт и OAuth-данные из проекта Google Cloud с включёнными Google Docs API и Google Drive API.\n\n1. [Подготовьте Google OAuth-доступ](#как-получить-доступ).\n2. Добавьте сервер в AI-приложение.\n3. Отправьте запрос, который только читает данные.\n\n<details open>\n<summary><strong>Codex</strong></summary>\n\n<br>\n\n**В приложении:** откройте **Settings → Plugins → MCP servers**, нажмите **Add server**, затем добавьте `npx -y @a1-x-tech/mcp-google-docs@latest` с `GOOGLE_DOCS_CLIENT_ID`, `GOOGLE_DOCS_CLIENT_SECRET` и `GOOGLE_DOCS_REFRESH_TOKEN`.\n\n**В командной строке:**\n\n```bash\ncodex mcp add google-docs \\\n  --env GOOGLE_DOCS_CLIENT_ID=your_client_id \\\n  --env GOOGLE_DOCS_CLIENT_SECRET=your_client_secret \\\n  --env GOOGLE_DOCS_REFRESH_TOKEN=your_refresh_token \\\n  -- npx -y @a1-x-tech/mcp-google-docs@latest\n```\n\n```bash\ncodex mcp list\n```\n\n[Документация Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)\n\n</details>\n\n<details>\n<summary><strong>Claude Code</strong></summary>\n\n<br>\n\n```bash\nclaude mcp add \\\n  --env GOOGLE_DOCS_CLIENT_ID=your_client_id \\\n  --env GOOGLE_DOCS_CLIENT_SECRET=your_client_secret \\\n  --env GOOGLE_DOCS_REFRESH_TOKEN=your_refresh_token \\\n  --transport stdio --scope user google-docs \\\n  -- npx -y @a1-x-tech/mcp-google-docs@latest\n```\n\n```bash\nclaude mcp list\n```\n\n[Документация Claude Code MCP](https://code.claude.com/docs/en/mcp)\n\n</details>\n\n<details>\n<summary><strong>Claude Desktop</strong></summary>\n\n<br>\n\nОткройте **Settings → Developer → Edit Config** и добавьте:\n\n```json\n{\n  \"mcpServers\": {\n    \"google-docs\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@a1-x-tech/mcp-google-docs@latest\"],\n      \"env\": {\n        \"GOOGLE_DOCS_CLIENT_ID\": \"your_client_id\",\n        \"GOOGLE_DOCS_CLIENT_SECRET\": \"your_client_secret\",\n        \"GOOGLE_DOCS_REFRESH_TOKEN\": \"your_refresh_token\"\n      }\n    }\n  }\n}\n```\n\nЕсли **Edit Config** недоступна, отредактируйте `~/Library/Application Support/Claude/claude_desktop_config.json` на macOS или `%APPDATA%\\Claude\\claude_desktop_config.json` на Windows.\n\n[Документация Claude Desktop MCP](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)\n\n</details>\n\n<details>\n<summary><strong>Cursor</strong></summary>\n\n<br>\n\nДобавьте в `~/.cursor/mcp.json` на macOS/Linux или `%USERPROFILE%\\.cursor\\mcp.json` на Windows:\n\n```json\n{\n  \"mcpServers\": {\n    \"google-docs\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@a1-x-tech/mcp-google-docs@latest\"],\n      \"env\": {\n        \"GOOGLE_DOCS_CLIENT_ID\": \"your_client_id\",\n        \"GOOGLE_DOCS_CLIENT_SECRET\": \"your_client_secret\",\n        \"GOOGLE_DOCS_REFRESH_TOKEN\": \"your_refresh_token\"\n      }\n    }\n  }\n}\n```\n\n[Документация Cursor MCP](https://cursor.com/docs/mcp)\n\n</details>\n\n<details>\n<summary><strong>VS Code</strong></summary>\n\n<br>\n\nЗапустите **MCP: Open User Configuration** и добавьте:\n\n```json\n{\n  \"servers\": {\n    \"google-docs\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@a1-x-tech/mcp-google-docs@latest\"],\n      \"env\": {\n        \"GOOGLE_DOCS_CLIENT_ID\": \"${input:docs_client_id}\",\n        \"GOOGLE_DOCS_CLIENT_SECRET\": \"${input:docs_client_secret}\",\n        \"GOOGLE_DOCS_REFRESH_TOKEN\": \"${input:docs_refresh_token}\"\n      }\n    }\n  },\n  \"inputs\": [\n    { \"type\": \"promptString\", \"id\": \"docs_client_id\", \"description\": \"Google OAuth client ID\" },\n    { \"type\": \"promptString\", \"id\": \"docs_client_secret\", \"description\": \"Google OAuth client secret\", \"password\": true },\n    { \"type\": \"promptString\", \"id\": \"docs_refresh_token\", \"description\": \"Google OAuth refresh token\", \"password\": true }\n  ]\n}\n```\n\nПроверьте сервер командой **MCP: List Servers**.\n\n[Документация VS Code MCP](https://code.visualstudio.com/docs/agent-customization/mcp-servers)\n\n</details>\n\n## Что можно поручить\n\n### Прочитать и выгрузить документ\n\n- Прочитай этот документ как текст с заголовками и таблицами и перескажи его.\n- Покажи дерево вкладок документа-справочника.\n- Выгрузи спецификацию в Markdown; сохрани договор в PDF-файл.\n\n### Написать и отредактировать текст\n\n- Создай документ с заметками встречи из этого Markdown.\n- Вставь абзац с выводами после введения.\n- Замени все «Q3» на «Q4» по всему документу.\n- Удали устаревший раздел с ценами.\n\n### Оформить и структурировать\n\n- Преврати эти абзацы в нумерованный список; сделай эту строку заголовком второго уровня.\n- Выдели ключевые термины жирным и добавь на них ссылки на глоссарий.\n- Вставь таблицу 3×4 для дорожной карты и заполни строку заголовков.\n- Добавь разрыв страницы перед приложением; вставь изображение по публичному URL.\n\n### Работать с комментариями\n\n- Перечисли открытые ветки комментариев и суммируй их.\n- Ответь на комментарий про дедлайн и отметь его решённым.\n- Добавь комментарий с цитатой предложения, которое нужно показать юристам.\n\n## Как меняется документ\n\n1. `create_document` создаёт **документ** — пустой или сразу сконвертированный из Markdown.\n2. Содержимое адресуется **индексами** — позициями UTF-16 внутри тела вкладки, — и каждая вставка или удаление сдвигает все последующие индексы. Сервер требует от ассистента брать свежие индексы из `read_document_text` перед каждой правкой и править с конца документа к началу.\n3. `import_markdown` заменяет **всё тело документа**: якоря комментариев, позиционированные объекты, колонтитулы и дополнительные вкладки конвертацию не переживают.\n4. **Вкладки** можно читать и адресовать, но API не умеет их создавать, переименовывать, удалять и переставлять.\n5. **Комментарии** живут в Drive и управляются как ветки. Новый комментарий нельзя привязать к диапазону текста — формат якоря не опубликован, — поэтому он добавляется на уровне документа, при желании с цитатой текста, к которому относится.\n\nЭкспорт ограничен 10 МБ и не включает комментарии и предложенные правки. Встраиваемые изображения Google скачивает по публичному URL (PNG/JPEG/GIF, до 50 МБ и 25 мегапикселей); канала загрузки файлов изображений нет.\n\n## Что может измениться\n\n| Операция | Что происходит | Граница подтверждения |\n|---|---|---|\n| Чтение документа, вкладок и комментариев | Читает содержимое и структуру | Ничего не меняет |\n| Экспорт документа | Пишет локальный файл, если задан `output_path`; сам документ не меняется | Меняет только локальные файлы |\n| Создание документа | Добавляет новый документ | Меняет Google Docs |\n| Вставка текста, таблицы, разрыва или изображения | Добавляет содержимое | Меняет документ |\n| Стили текста и абзацев, управление списками | Перезаписывает форматирование диапазона | Меняет документ |\n| Замена или удаление диапазона, поиск с заменой | Удаляет существующее содержимое | Разрушительно |\n| Замена всего документа из Markdown | Заменяет всё тело документа | Разрушительно |\n| Управление комментариями | Создаёт, отвечает, закрывает или безвозвратно удаляет | Потенциально разрушительно |\n| Технический запрос API | Может вызвать метод API без отдельного инструмента | Потенциально разрушительно |\n\nКак AI-приложение просит подтверждение, определяет само приложение. Сервер помечает операции чтения, записи и удаления, чтобы оно отличило проверку от рабочего изменения.\n\n## Как получить доступ\n\nGoogle Docs требует OAuth 2.0: одного API-ключа недостаточно.\n\n1. Создайте или выберите проект Google Cloud и включите оба API — **Google Docs API** и **Google Drive API** (экспорт, конвертация Markdown и комментарии идут через эндпоинты Drive).\n2. Настройте OAuth consent screen и создайте OAuth-клиент типа **Desktop app**.\n3. Авторизуйте Google-аккаунт, который владеет документами или может их редактировать. [OAuth 2.0 Playground](https://developers.google.com/oauthplayground) поможет получить refresh token, если включить **Use your own OAuth credentials**.\n4. Запросите оба scope:\n\n   ```text\n   https://www.googleapis.com/auth/documents\n   https://www.googleapis.com/auth/drive\n   ```\n\n   Для более узкой настройки достаточно `drive.file`, если экспорт, Markdown и комментарии касаются только документов, созданных этим OAuth-клиентом, а пары `documents.readonly` + `drive.readonly` хватает для инструментов, которые только читают.\n\nRefresh token OAuth-приложения в режиме Testing может истечь через семь дней. Для долгого доступа опубликуйте OAuth-приложение или используйте Internal-приложение в домене Workspace. Храните client secret и refresh token как пароли.\n\n## Конфигурация\n\n| Переменная | Обязательна | Описание |\n|---|---|---|\n| `GOOGLE_DOCS_CLIENT_ID` | Да* | OAuth client ID. |\n| `GOOGLE_DOCS_CLIENT_SECRET` | Да* | OAuth client secret. |\n| `GOOGLE_DOCS_REFRESH_TOKEN` | Да* | OAuth refresh token. |\n| `GOOGLE_DOCS_ACCESS_TOKEN` | Да* | Короткоживущая альтернатива OAuth-тройке (~1 час). |\n| `GOOGLE_DOCS_API_BASE` | Нет | Переопределяет базовый URL Google Docs API. |\n| `GOOGLE_DOCS_DRIVE_API_BASE` | Нет | Переопределяет базовый URL Drive API (экспорт, Markdown, комментарии). |\n| `GOOGLE_DOCS_TIMEOUT_MS` | Нет | Тайм-аут одного запроса; по умолчанию `60000` мс. |\n| `GOOGLE_DOCS_MAX_RETRIES` | Нет | Повторы временных ошибок; по умолчанию `3`. |\n\n\\* Передайте OAuth-тройку или access token.\n\n## Данные, лимиты и работа в фоне\n\n- **Запросы идут в Google.** Локальный сервер обновляет OAuth-токены Google и вызывает Docs API; экспорт, конвертация Markdown и комментарии внутри используют эндпоинты Drive API. Анонимная телеметрия содержит ID установки, версию пакета, версии AI-клиента и платформы и имена инструментов — но не OAuth-токены, содержимое документов, аргументы или промпты. Чтобы отключить её, задайте `ASKADS_TELEMETRY=0`.\n- **У Google есть поминутные квоты.** При `429` сервер выдерживает паузу и повторяет запрос; чтение также повторяется после сетевых и `5xx` ошибок, а запись после неопределённой ошибки не повторяется никогда — повторённая запись могла бы продублировать правку.\n- **Постоянного опроса нет.** Сервер работает только при вызове. Если AI-приложение поддерживает задания по расписанию, оно может периодически проверять документ или его комментарии.\n\n## Техническая документация\n\n- [Каталог MCP-возможностей](./docs/capabilities/index.md) — страницы по пользовательским задачам для каждого инструмента.\n- [Все инструменты и параметры](./docs/TOOLS.md)\n- [Документация по разработке](./docs/DEVELOPMENT.md)\n- [Документация по публикации](./docs/PUBLISHING.md)\n- [Справочник Google Docs API](https://developers.google.com/docs/api)\n\n## Поддержка\n\nНашли ошибку или не хватает сценария? [Создайте issue](https://github.com/A1-x-Tech/mcp-google-docs/issues) или напишите в [Telegram](https://t.me/a1_mcp).\n\n<br>\n\n<p align=\"center\">\n  <img src=\"https://github.com/ztemerbekov/a1-yandex-kit-skills/raw/main/assets/images/mona-hifive-yandex-kit-warm.gif\" alt=\"Две Моны дают пять\" width=\"256\">\n</p>\n\n<p align=\"center\">\n  Вы дочитали до конца!\n</p>\n","readmeFilename":"README.ru.md","_rev":"1-141c14c551f15b5ee53b8c8b088e424d"}