Skip to main content
Glama

Google Apps Script MCP

English | Русский

npm Glama CI License: MIT

A1 Google Apps Script MCP lets an AI app write and operate Google Apps Script in plain language. Create a script project, read and edit its code, snapshot versions, manage deployments, run functions and read the execution history.

It uses the Google Apps Script API with your Google account. It distinguishes the editable HEAD code from immutable versions and makes the limits of the Apps Script API explicit instead of implying that every scripting task is possible.

  • 19 tools. Create standalone and bound projects, read and update code files, snapshot immutable versions, manage deployments, run functions, and inspect execution history and metrics.

  • Connects from the conversation. Say "connect Google Apps Script": the server walks you through the OAuth client, catches Google's redirect on 127.0.0.1 with PKCE and keeps the tokens itself — no config files, no restart.

  • Versions are immutable. A version snapshots HEAD and can never be edited or deleted; deployments point at versions, so you ship and roll back without changing a URL.

  • The manifest always survives. Merge mode keeps the appsscript manifest and every file you did not mention; replace mode refuses a file set without the manifest before any network traffic.

  • Keep your scriptId. The API cannot list projects and cannot delete them — the scriptId returned by create_project is the only handle.

  • Minimal Google scopes. Each operation names its own scope (script.projects, script.deployments, script.processes, script.metrics); request only what your tasks need.

Start with a read-only question:

Show me the files in my report script and which functions failed this week.

Connect the server · Explore use cases · Open technical documentation


See it work in a minute

You: Show the code and the recent runs of my report script.

Assistant: Shows every file with its source and the execution history — which functions ran, when, and which failed. Nothing changes.

You: Add a formatDate helper to the Utils file and keep everything else as is.

Assistant: Shows the proposed source and confirms that merge mode leaves the other files untouched, then asks for confirmation before writing.

You: Confirm.

Assistant: Writes the file to HEAD. It does not create a version, redeploy or run anything unless you ask separately.

Related MCP server: claude-appsscript-pro

Contents

Quick start

You need Node.js 20+ and a Google account. Credentials are not required at install time — the server connects from the conversation.

  1. Add the server to your AI app.

  2. Say "connect Google Apps Script": the assistant walks you through creating the OAuth client and approving access without editing config files.

  3. Ask the read-only question above.

In the app: open Settings → MCP servers, select Add server, choose STDIO, enter the command npx -y mcp-google-apps-script@latest and environment variables GOOGLE_APPS_SCRIPT_CLIENT_ID, GOOGLE_APPS_SCRIPT_CLIENT_SECRET, GOOGLE_APPS_SCRIPT_REFRESH_TOKEN, then select Save and Restart.

From the command line:

codex mcp add google-apps-script \
  -- npx -y mcp-google-apps-script@latest
codex mcp list

Codex MCP documentation

claude mcp add \
  --transport stdio --scope user google-apps-script \
  -- npx -y mcp-google-apps-script@latest
claude mcp list

Claude Code MCP documentation

The current official path is Settings → Extensions. For a custom desktop extension, open Advanced settings → Extension Developer → Install Extension…, select a .mcpb file and follow the prompts.

This repository currently publishes an npm stdio package and does not contain a .mcpb bundle. For Claude Desktop builds that still support local configuration, use the following JSON stdio configuration as a fallback:

{
  "mcpServers": {
    "google-apps-script": {
      "command": "npx",
      "args": ["-y", "mcp-google-apps-script@latest"]
    }
  }
}

In those builds, save it to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows.

Claude Desktop MCP documentation

Add this to ~/.cursor/mcp.json on macOS/Linux or %USERPROFILE%\.cursor\mcp.json on Windows:

{
  "mcpServers": {
    "google-apps-script": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-apps-script@latest"]
    }
  }
}

Cursor MCP documentation

Run MCP: Open User Configuration and add:

{
  "servers": {
    "google-apps-script": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-apps-script@latest"]
    }
  }
}

Check it with MCP: List Servers.

VS Code MCP documentation

What you can ask it to do

Inspect a project and its runs

  • Show this script's files and explain what each function does.

  • Which functions failed this week? Show the execution history for sendDigest.

  • How many users, executions and failures did this script have over the last 7 days?

Write and evolve code

  • Create a standalone project, or a script bound to a Doc, Sheet, Slides or Form.

  • Add a helper function to one file without touching the others.

  • Snapshot the current code as a version with a description before we refactor.

Ship, run and roll back

  • Deploy version 4 and show its entry points — web app URL or API-executable config.

  • Run sendDigest and show the result; if the script throws, show the stack trace.

  • Repoint the deployment back to version 3 without changing its URL.

How a project changes

  1. create_project creates a project — standalone, or bound to a Doc, Sheet, Slides or Form. Keep the returned scriptId: the API cannot list projects.

  2. Code lives at HEAD as files addressed by name without extension. update_project_content merges by default — it upserts the files you name and keeps the rest — and only replaces the entire set when asked; the appsscript manifest can never be deleted.

  3. create_version snapshots HEAD as an immutable version — no edit, no delete, numbers only grow.

  4. A deployment exposes a version as a web app or API executable. Updating a deployment repoints it at another version without changing its URL; the automatic @HEAD deployment cannot be deleted.

The API cannot delete a project either — that means deleting its Drive file, which this server does not cover. run_function requires an API-executable deployment, an OAuth client from the same Cloud project as the script and the script's own scopes on the token; Apps Script stops any execution after 6 minutes. The execution history shows status and timing but no error messages — those live in Cloud Logging or come from re-running the function.

What can change

Operation

What happens

Confirmation boundary

Read a project, its code, versions, runs or metrics

Reads data

No change

Create a project

Adds a standalone or bound script project

Changes Google Apps Script

Update project files

Overwrites code at HEAD; replace mode swaps the entire file set

Changes a project

Create a version

Adds an immutable snapshot that can never be removed

Changes a project

Create or update a deployment

Changes what a live URL or API endpoint serves

Changes a project's live behavior

Delete a deployment

Permanently breaks the deployment URL

Destructive

Run a function

Executes real code with real side effects

Destructive

Raw API request

Can call API methods without a dedicated tool

Potentially destructive

The AI client controls confirmation prompts. The server marks reads, writes and destructive tools so the client can distinguish an inspection from a live change.

Getting access

Google Apps Script requires OAuth 2.0; an API key is not enough. There are two ways in, and the first one needs no configuration files.

Say "connect Google Apps Script" and the assistant runs the flow with you:

  1. setup_instructions prints the checklist: create or select a Google Cloud project, enable Apps Script API, configure the consent screen and create a Desktop app OAuth client.

  2. Download that client's JSON ("Download JSON") and give the assistant its path — set_client stores it owner-only. The secret never goes through the conversation.

  3. start_login returns a Google consent link. Open it on this machine and approve; the code comes back to a one-shot listener on 127.0.0.1 (PKCE), never through the chat.

  4. finish_login exchanges the code and saves the tokens to ~/.config/mcp-google-apps-script/credentials.json (mode 0600) and verifies them with a real Apps Script API call — so an API that is still switched off is caught right there.

The tokens are re-read on every call, so the connection works immediately — no restart of the AI app. auth_status shows what is connected, logout revokes and deletes it.

Environment variables (CI, unattended installs)

  1. Create or select a Google Cloud project and enable Google Apps Script API.

  2. Turn on the per-account toggle at script.google.com/home/usersettings — without it every call fails with 403.

  3. Configure the OAuth consent screen and create a Desktop app OAuth client.

  4. Authorize the Google account that owns the scripts. The OAuth 2.0 Playground can obtain the refresh token when Use your own OAuth credentials is enabled.

  5. Request the scopes for the tools you plan to use:

    https://www.googleapis.com/auth/script.projects
    https://www.googleapis.com/auth/script.deployments
    https://www.googleapis.com/auth/script.processes
    https://www.googleapis.com/auth/script.metrics

    For inspection-only use, replace the first two with the read-only variants script.projects.readonly and script.deployments.readonly; list_processes and get_project_metrics still need script.processes and script.metrics, which have no narrower form. run_function needs none of these scopes — instead the token must carry every scope the target script itself uses, and the OAuth client must belong to the same Cloud project as the script.

Testing-mode OAuth refresh tokens can expire after seven days. Publish the OAuth app, or use an Internal app in a Workspace domain, when you need long-lived access. Treat the client secret and refresh token as passwords.

The setup_instructions tool returns this same checklist and works even before credentials are configured.

Configuration

Every variable is optional — with none of them the server connects from the chat.

Variable

Required

Description

GOOGLE_APPS_SCRIPT_CLIENT_ID

No*

OAuth client ID.

GOOGLE_APPS_SCRIPT_CLIENT_SECRET

No*

OAuth client secret.

GOOGLE_APPS_SCRIPT_REFRESH_TOKEN

No*

OAuth refresh token.

GOOGLE_APPS_SCRIPT_ACCESS_TOKEN

No*

Short-lived alternative to the OAuth trio.

GOOGLE_APPS_SCRIPT_OAUTH_PORT

No

Fixed loopback port for the in-chat login; useful over SSH port forwarding.

GOOGLE_APPS_SCRIPT_API_BASE

No

Google Apps Script API base URL override.

GOOGLE_APPS_SCRIPT_TIMEOUT_MS

No

Per-request timeout; default 60000 ms.

GOOGLE_APPS_SCRIPT_MAX_RETRIES

No

Temporary-error retries; default 3.

* Provide either the OAuth trio or an access token.

Data, limits and background work

  • Requests go to Google Apps Script. The local server refreshes Google OAuth tokens and calls the Apps Script API. Its anonymous telemetry contains an installation ID, package version, AI client and platform versions, and tool names — never OAuth tokens, script sources, tool arguments or prompts. For each tool call it also sends the outcome and, on failure, an excerpt of the error text with e-mails, addresses, tokens, numbers of 4+ digits and quoted text replaced by #; a value from your request can appear in it if the error text contains it. Set ASKADS_TELEMETRY=0 to opt out.

  • Writes are never replayed blindly. On 429, the server uses backoff; reads also retry after network and 5xx errors, while writes are not replayed after an uncertain failure — a duplicated create_version piles up immutable versions, and a duplicated run_function executes side effects twice. After an ambiguous failure, check list_versions or the execution history instead of re-sending.

  • There is no background polling. The server runs only when called, and a function executes only when you ask for it. Scripts keep their own Apps Script triggers on Google's side; if your AI app supports scheduled tasks, it can also check the execution history periodically.

Technical documentation

Support

Found a bug or need a scenario? Create an issue or write in Telegram.

Available Tools

18 tools
auth_statusGoogle connection statusA
Read-onlyIdempotent

Shows whether this server is connected to Google: token presence and source (env variables or a stored in-chat login), expiry, the Google account email, granted vs missing OAuth scopes, where the credentials file lives and where the OAuth client comes from. Makes no network calls and never returns the token itself. Call it first when other tools report the server is not connected.

Inputs: no named parameters.

create_projectCreate a script projectA

Creates an Apps Script project and returns it (scriptId, title, createTime). Without parent_id the project is standalone (its scriptId doubles as its Drive file id); with parent_id — the Drive id of a Google Doc, Sheet, Slides or Form — the project is created bound to that container and can use its container-specific APIs (e.g. SpreadsheetApp.getActive()). A new project holds only a default manifest and an empty Code file: add real code with update_project_content next. IMPORTANT: the API cannot list or delete projects — keep the returned scriptId, it is the only handle. Requires the script.projects scope, the Apps Script API toggle at script.google.com/home/usersettings, and — for bound projects — access to the parent file.

Inputs: title (required), parent_id.

create_versionCreate a versionA

Snapshots the project's current HEAD content as a new immutable version and returns it (versionNumber, description, createTime). Versions cannot be edited or deleted, and version numbers only grow — every call creates a NEW version, so do not re-send after an ambiguous failure without checking list_versions first. Creating a version does not change what runs anywhere: point a deployment at the new versionNumber via manage_deployments (action=create or update) to ship it.

Inputs: script_id (required), description.

finish_loginFinish the Google loginA
Idempotent

Second step: waits up to 20 s for the browser consent to finish, saves the tokens to an owner-only file and verifies the login with a read-only identity call, returning the account email and the granted scopes. After success every tool works immediately — no client restart. If the user granted only part of the requested permissions, the login is still saved and missingScopes lists what will not work. Logging in under a different Google account replaces the previous login (its refresh token is revoked best-effort) and the response carries previousAccountEmail so the change never goes unnoticed.

Inputs: no named parameters.

get_projectGet project metadataA
Read-onlyIdempotent

Returns the project's metadata: title, scriptId, parentId (present only for bound projects), creator, lastModifyUser, createTime and updateTime. No code is included — use get_project_content for the files. Useful to verify a scriptId exists and check whether the project is standalone or bound.

Inputs: script_id (required).

get_project_contentGet project filesA
Read-onlyIdempotent

Returns the project's full file set: files[] with name (no extension), type (SERVER_JS = .gs code, HTML, JSON = the "appsscript" manifest), source, and per-file update info. By default HEAD (the latest saved code) is returned; version_number returns the content of that immutable version instead. Call this before update_project_content: replace mode needs the full new set including the manifest, and merge mode addresses files by these exact names.

Inputs: script_id (required), version_number.

get_project_metricsGet execution metricsA
Read-onlyIdempotent

Returns execution metrics for the project: activeUsers, totalExecutions and failedExecutions as time series ({ value, startTime, endTime }; value is absent when zero). granularity daily covers the last 7 days, weekly aggregates by week. deployment_id narrows the numbers to one deployment. A rising failedExecutions count is the cue to call list_processes with statuses=[FAILED] for the concrete failures. Requires the script.metrics scope.

Inputs: script_id (required), granularity (required), deployment_id.

get_versionGet a versionA
Read-onlyIdempotent

Fetches one immutable version by its number: versionNumber, description and createTime. For the code of that version call get_project_content with version_number instead — this endpoint returns metadata only.

Inputs: script_id (required), version_number (required).

list_processesList execution processesA
Read-onlyIdempotent

Lists execution processes (the execution history): each entry carries projectName, functionName, processType (WEBAPP, EXECUTION_API, TIME_DRIVEN, TRIGGER, SIMPLE_TRIGGER, ADD_ON, EDITOR, MENU, BATCH_TASK), processStatus (COMPLETED, FAILED, TIMED_OUT, RUNNING, PAUSED, CANCELED, DELAYED, UNKNOWN), userAccessLevel, startTime and duration. With script_id only that script's executions are listed; without it, ALL executions started by the authorizing user across their scripts. To hunt errors, filter statuses=["FAILED","TIMED_OUT"] — but note the API returns no error messages or logs here, only the fact and time of failure: get the message by re-running via run_function, or from the Apps Script dashboard / Cloud Logging. start_time/end_time (RFC3339 UTC) bound the process start; paginate with page_token. Requires the script.processes scope.

Inputs: types, end_time, statuses, page_size, +5 more.

list_versionsList versionsA
Read-onlyIdempotent

Lists the project's immutable versions (versionNumber, description, createTime), newest first. Paginate with page_token from nextPageToken. Use it to pick a versionNumber for manage_deployments or to read old code via get_project_content with version_number.

Inputs: script_id (required), page_size, page_token.

logoutDisconnect from GoogleA
Destructive

Revokes the stored token at Google (oauth2.googleapis.com/revoke) and deletes the local credentials file. Tokens supplied via env variables are NOT touched — remove them from the MCP client config manually; envTokenStillSet in the response says whether any are still in effect.

Inputs: no named parameters.

manage_deploymentsManage deploymentsA
Destructive

Manages the project's deployments — the published entry points (web app, API executable, add-on) that make code callable from outside the editor. action=create deploys version_number (omit it to deploy HEAD — updates live with every save; fine for testing, risky for production) with an optional description. action=list shows all deployments including the automatic @HEAD one (paginate with page_token from nextPageToken); get needs deployment_id and returns entryPoints[] — the web app URL (webApp.url) and the API-executable config run_function depends on. action=update repoints an existing deployment at another version_number and/or changes its description (this is how you ship or roll back without changing the URL; the current config is read first and merged, so omitted fields are preserved); delete removes it permanently and breaks its URL/integrations (the @HEAD deployment cannot be deleted). WHAT a deployment exposes (web app vs API executable, who can access) comes from the appsscript manifest at the deployed version — set it via update_project_content before creating the version. Requires the script.deployments scope.

Inputs: action (required), script_id (required), page_size, page_token, +3 more.

raw_requestRaw Google Apps Script API callA
Destructive

Escape hatch to call any Google Apps Script API v1 path directly, for requests the typed tools don't cover — e.g. GET "v1/projects//content?versionNumber=3", or a PUT to "v1/projects//content" with a hand-built files body. The path may carry a query string; repeated filter params can be encoded there (e.g. "v1/processes?userProcessFilter.statuses=FAILED&userProcessFilter.statuses=TIMED_OUT"). The Bearer token is added automatically and paths resolving to a foreign origin are rejected; the method defaults to GET. Remember: PUT v1/projects//content replaces the ENTIRE file set — prefer update_project_content, whose merge mode protects the other files.

Inputs: path (required), body, method.

run_functionRun a script functionA
Destructive

Runs a named function in the script and returns { done, result } — or, when the script itself throws, { done, script_error: { type, message, stack } } with the Apps Script stack trace (this is a script bug, not a transport error; do not blindly retry, the function may have side effects). HARD PREREQUISITES the API enforces: (1) the script must have an API-executable deployment (Deploy > New deployment > API executable, or a manifest with executionApi); (2) this server's OAuth client must belong to the SAME Google Cloud project as the script (script editor > Project Settings > change the GCP project number); (3) the OAuth token must carry every scope the script itself uses (listed in the editor under Project Settings > Show "appsscript.json") — otherwise the call fails with 403 PERMISSION_DENIED or 404. parameters are positional and must be JSON-serializable (no Apps Script objects like Document or Range). dev_mode=true runs the latest saved code instead of the deployed version — owner only. Executions time out after 6 minutes on the Apps Script side.

Inputs: script_id (required), function_name (required), dev_mode, parameters.

set_clientSave the OAuth clientA
Idempotent

Saves the OAuth client credentials from the JSON file downloaded from Google Cloud Console ('Download JSON' on a Desktop-app client). Pass the file PATH — the secret must never be pasted into the chat. The client is stored once in the shared ~/.config/mcp-google-auth/client.json (owner-only) and reused by every mcp-google-* server; tokens stay per-server. After this, call start_login.

Inputs: path (required).

setup_instructionsSetup instructionsA
Read-onlyIdempotent

Returns the setup checklist for this server as structured JSON: how to enable the Apps Script API (the per-account toggle at script.google.com/home/usersettings AND the Cloud-project API), which OAuth scope each tool needs (so the operator can mint a minimal-scope refresh token), the extra prerequisites of run_function (API-executable deployment, same-Cloud-project OAuth client, the script's own scopes), and the API's known limits. Works without credentials — call it first when any tool fails with 403 PERMISSION_DENIED or when setting the server up.

Inputs: no named parameters.

start_loginStart the Google loginA
Idempotent

First step of connecting from the chat, without editing config files or restarting the client. Returns authorizeUrl — show it to the user as a clickable link and ask them to open it in the browser ON THIS MACHINE, pick the Google account and approve access. A one-shot listener on 127.0.0.1 catches Google's redirect; the code is exchanged locally and never passes through the chat. Does not open the browser itself. The attempt lives 10 minutes; when the browser shows the success page, call finish_login.

Inputs: no named parameters.

update_project_contentUpdate project filesA
DestructiveIdempotent

Writes code files to the project's HEAD (deployed versions are untouched until you create a version + deployment). Two modes. mode="merge" (default, safer): the current content is read first, the given files are added or overwritten BY NAME, delete_files removes named files, everything else is preserved — not atomic, a concurrent edit between read and write is lost. mode="replace": the given files become the ENTIRE project; any file not in the list is deleted, and the list must include the "appsscript" manifest (type json) or the call is rejected before hitting the API. File names carry no extension ("Code", not "Code.gs"); the manifest cannot be deleted. Returns the resulting file set. This write is never retried after a 5xx or timeout — check with get_project_content before re-sending.

Inputs: files (required), script_id (required), mode, delete_files.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 18 tools

    Disambiguation4/5

    Tools target clearly distinct resources and actions (auth flow, project CRUD, content, versions, deployments, processes, metrics, run, raw escape hatch), and descriptions disambiguate the tricky pairs (get_version metadata vs get_project_content with version_number, create_version vs manage_deployments action=create). Minor blurring comes from manage_deployments bundling five actions and raw_request overlapping everything, but both are explicitly framed.

    Naming Consistency4/5

    The dominant pattern is verb_noun (create_project, get_project_content, list_versions, run_function, finish_login), applied consistently. A few names deviate to noun/state style (auth_status, setup_instructions, raw_request) but remain readable and each fits a distinct role.

    Tool Count4/5

    18 tools is on the heavier side but justified for a full Apps Script API surface plus the OAuth login flow. Each tool maps to a real operation; only the deployment bundle could arguably be split, so it is slightly over rather than bloated.

    Completeness4/5

    Core lifecycle is covered: project create/get, content read/write, versioning, deployments, execution history, metrics, running functions, and a raw_request escape hatch for gaps. Known API limits (no project list/delete) are documented, but the absence of any delete-project or version-delete path means a few dead ends remain.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables users to create, manage, and execute Google Apps Script projects through natural language. It provides comprehensive tools for code editing, function execution, deployment management, and monitoring script processes.
      50
      10
      MIT
    • A
      license
      D
      quality
      D
      maintenance
      Enables AI-driven development and management of Google Apps Script projects, including autonomous system construction, real-time debugging, and spreadsheet operations through natural language.
      76
      6
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to directly read and write Google Apps Script projects, including editing code, managing versions and deployments, and diagnosing trigger failures, with automatic version backups before any write operation.
      9 npm
      ISC
    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI assistants to directly read and write Google Apps Script projects, manage versions and deployments, inspect execution logs and failures, and run functions through natural language, with user-owned OAuth authorization and self-hosted deployment.
      -