# General Translation Integrations: Google Drive MCP tools
URL: https://generaltranslation.com/en-GB/docs/integrations/google-drive/reference/mcp-tools.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Translate Google Docs, Google Sheets, and Google Slides through the authenticated hosted MCP server. API reference for the Google Drive MCP tools.

The hosted server at `https://api.gtx.dev/mcp` exposes three tools for finding connected projects, starting translations, and polling their progress. These tools use the same Google Drive connections and translated copies as the Dashboard integration and support Google Docs, Google Sheets, and Google Slides.

## Overview [#overview]

| Tool                                                   | Description                                                                       | Permission                                               |
| ------------------------------------------------------ | --------------------------------------------------------------------------------- | -------------------------------------------------------- |
| [Authentication and access](#access)                   | Choose credentials and a Google Drive connection mode.                            | —                                                        |
| [`get_google_drive_context`](#drive-context)           | Lists accessible connected projects and resolves optional file context.           | `project:files:read`                                     |
| [`translate_google_drive_file`](#translate-drive-file) | Synchronises and translates one Google Docs, Google Sheets or Google Slides file. | `project:files:write` and `project:translations:enqueue` |
| [`get_google_drive_translation_status`](#drive-status) | Returns translation progress, layout progress and translated-copy URLs.           | `project:files:read`                                     |

## Authentication and access [#access]

Connect to the [hosted MCP server](/docs/overview/for-coding-agents#mcp) with OAuth or an accepted API key:

* **OAuth:** the tools can use your linked personal Google account or the project&#39;s Organisation shared drive connection. A legacy personal connection with only `drive.file` access can reach Dashboard-selected files, but it must be reconnected with full Drive access before a tool can translate another file.
* **Project API key:** the key must include the permissions required by the tool, and the project must use an Organisation shared drive connection.
* **Organisation API key:** the key must include the permissions required by the tool and target a project that uses an Organisation shared drive connection.
* **Locadex:** the project must use an Organisation shared drive connection.

An API-key caller cannot use a personal Google account for Drive access. The Organisation needs the project integrations feature, and Organisation shared drive access also requires its separate Enterprise feature. Configure both connection modes in the [Connection reference](/docs/integrations/google-drive/reference/connection).

MCP and API calls enforce the permission listed for each tool. Dashboard file actions require `project:files:write` and `project:translations:enqueue`, while the page separately checks `translations:content:write` before showing personal-account controls.

## `get_google_drive_context` [#drive-context]

**Read-only** · **Permission** `project:files:read`

Call this tool first to list the projects the current credential can access and obtain their project IDs and locale settings. You can also resolve the source and locale context for a Google Drive file.

### Inputs

| Name      | Description                                                            | Type                             | Optional | Default |
| --------- | ---------------------------------------------------------------------- | -------------------------------- | -------- | ------- |
| `fileId`  | Google Drive file ID from the Docs, Sheets, or Slides URL after `/d/`. | `string`                         | Yes      | —       |
| `hostApp` | Google editor that owns the file.                                      | `'DOCS' \| 'SLIDES' \| 'SHEETS'` | Yes      | —       |

Omit both inputs to list connected projects. Provide both to inspect a source file or a translated copy managed by the integration.

### Returns

The result includes:

* `user.email`, which can be `null` and does not indicate whether a personal Google account is connected.
* Supported locales.
* Accessible projects with their IDs, names, default source locales, current locales, locale allowlists, and integration status.
* Source and target locale context when the requested file is linked or is a managed translated copy.

Projects whose connection mode the caller cannot use are omitted.

## `translate_google_drive_file` [#translate-drive-file]

**Mutating** · **Permissions** `project:files:write` and `project:translations:enqueue`

Synchronises one Google Docs, Google Sheets, or Google Slides file, imports edits from existing translated copies, queues translation work, and applies completed translations to the managed copies.

### Inputs

| Name            | Description                                                                                           | Type                             | Optional | Default                          |
| --------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------- | -------- | -------------------------------- |
| `projectId`     | Project ID returned by `get_google_drive_context`.                                                    | `string`                         | No       | —                                |
| `fileId`        | Google Drive file ID from the Docs, Sheets, or Slides URL after `/d/`.                                | `string`                         | No       | —                                |
| `hostApp`       | Google editor that owns the file.                                                                     | `'DOCS' \| 'SLIDES' \| 'SHEETS'` | No       | —                                |
| `targetLocales` | One to 100 supported locale codes. When the project has a locale allowlist, every code must be on it. | `string[]`                       | No       | —                                |
| `sourceLocale`  | Source locale. Falls back to the stored file locale, then the project default.                        | `string`                         | Yes      | Stored locale or project default |
| `force`         | Retranslates existing content instead of reusing it.                                                  | `boolean`                        | Yes      | `false`                          |

When `fileId` identifies a managed translated copy, the tool resolves its original source and uses only that copy&#39;s target locale. Its original source locale also overrides `sourceLocale`.

The tool drops a target code that exactly matches the resolved source. The request fails before anything is queued if no target remains, or if a target is a broader or narrower code for the source language, such as `en` and `en-GB`. To translate between variants, use two codes that differ in region or script, such as `en-US` and `en-GB`.

### Returns

The result contains `accepted`, the resolved `sourceLocale` and `targetLocales`, counts in `enqueued` and `failed`, and an `errors` array. Inspect all three outcome fields because one target locale can fail while others are queued.

Locale validation errors fail the whole request instead of returning this result.

This tool may consume translation credits and update existing translated copies. Forced translation can overwrite translated text and layout changes.

## `get_google_drive_translation_status` [#drive-status]

**Read-only** · **Permission** `project:files:read`

Poll this tool after `translate_google_drive_file` to read translation and layout progress for every requested locale.

### Inputs

| Name        | Description                                                            | Type                             | Optional | Default |
| ----------- | ---------------------------------------------------------------------- | -------------------------------- | -------- | ------- |
| `projectId` | Project ID returned by `get_google_drive_context`.                     | `string`                         | No       | —       |
| `fileId`    | Google Drive file ID from the Docs, Sheets, or Slides URL after `/d/`. | `string`                         | No       | —       |
| `hostApp`   | Google editor that owns the file.                                      | `'DOCS' \| 'SLIDES' \| 'SHEETS'` | No       | —       |

### Returns

Each locale result contains its locale details, nullable `translationProgress` and `layoutProgress` values, and a `done` boolean. Only Google Slides has a layout pass, so `layoutProgress` stays `null` for Google Docs and Google Sheets. Once a managed copy is available, `targetCopy` contains its Google Drive file ID and a URL that opens in the editor named by `hostApp`.

When `fileId` identifies a managed translated copy, the tool resolves its source and returns status for that copy&#39;s target locale.

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.
