google-apps-script-mcp by nikolai-cardinal - MCP Server

Google Apps Script MCP Server

A Model Context Protocol (MCP) server that enables AI agents (like Claude) to programmatically create, read, update, and deploy Google Apps Script projects.

Project Goal

Enable AI-powered automation of Google Apps Script development - allowing Claude Code and other MCP-compatible AI agents to:

Create new Apps Script projects (standalone or bound to Sheets/Docs/Forms)
Read and update script content programmatically
Deploy scripts as web apps, add-ons, or API executables
Execute Apps Script functions remotely
Manage versions and deployments

This eliminates the copy/paste workflow and allows true end-to-end automation of Google Workspace scripting.

Why This Matters

Current Workflow	With This MCP Server
User describes need	User describes need
AI writes code	AI writes code
User manually copies to Apps Script editor	AI deploys directly
User tests and reports errors	AI tests and debugs
Repeat...	Done!

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                        Claude Code / AI Agent                    │
└─────────────────────────────────────────────────────────────────┘
                                │
                                │ MCP Protocol (stdio/SSE)
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Google Apps Script MCP Server                  │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                    MCP Tool Handlers                     │    │
│  │  • create_project    • get_project    • update_content  │    │
│  │  • get_content       • create_version • deploy          │    │
│  │  • list_deployments  • run_function   • get_logs        │    │
│  └─────────────────────────────────────────────────────────┘    │
│                              │                                   │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                  OAuth2 Authentication                   │    │
│  │         (Google Cloud Platform Credentials)              │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
                                │
                                │ HTTPS REST API
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Google Apps Script API                        │
│                   (script.googleapis.com/v1)                     │
└─────────────────────────────────────────────────────────────────┘

Core MCP Tools (Planned)

Project Management

Tool	Description
`create_project`	Create a new Apps Script project (standalone or bound)
`get_project`	Get project metadata (title, script ID, creator, etc.)
`list_projects`	List all Apps Script projects accessible to the user
`delete_project`	Delete an Apps Script project

Content Management

Tool	Description
`get_content`	Retrieve all files from a project (code, HTML, manifest)
`update_content`	Update/replace project files
`add_file`	Add a new file to a project
`delete_file`	Remove a file from a project

Version & Deployment

Tool	Description
`create_version`	Create a new immutable version
`list_versions`	List all versions of a project
`create_deployment`	Deploy a version (web app, add-on, API executable)
`update_deployment`	Update an existing deployment to a new version
`list_deployments`	List all deployments
`delete_deployment`	Archive/delete a deployment

Execution & Debugging

Tool	Description
`run_function`	Execute a function in the Apps Script project
`get_logs`	Retrieve execution logs
`get_metrics`	Get project metrics (executions, errors, users)

Prerequisites

Before building this MCP server, you'll need:

1. Google Cloud Platform Project

Create a GCP project at console.cloud.google.com
Enable the Apps Script API
Enable the Google Drive API (for bound scripts)

2. OAuth 2.0 Credentials

Create OAuth 2.0 Client ID (Desktop Application type)
Download the credentials JSON file
Required scopes:
- https://www.googleapis.com/auth/script.projects
- https://www.googleapis.com/auth/script.deployments
- https://www.googleapis.com/auth/script.metrics
- https://www.googleapis.com/auth/drive.file (for bound scripts)

3. Development Environment

Node.js 18+ (LTS recommended)
npm or pnpm
TypeScript knowledge (optional but recommended)

Tech Stack

Component	Technology	Reason
Runtime	Node.js 18+	MCP SDK support, async/await
Language	TypeScript	Type safety, better DX
MCP SDK	`@modelcontextprotocol/sdk`	Official MCP implementation
Google Auth	`google-auth-library`	Official Google OAuth
Google APIs	`googleapis`	Official Google API client
HTTP Server	Built-in (stdio)	MCP standard transport

Project Structure (Planned)

google-apps-script-mcp/
├── README.md                 # This file
├── package.json              # Node.js dependencies
├── tsconfig.json             # TypeScript configuration
├── .env.example              # Environment variables template
├── .gitignore                # Git ignore rules
│
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── server.ts             # MCP server setup
│   │
│   ├── auth/
│   │   ├── oauth.ts          # OAuth2 flow implementation
│   │   └── credentials.ts    # Credential management
│   │
│   ├── tools/
│   │   ├── projects.ts       # Project management tools
│   │   ├── content.ts        # Content management tools
│   │   ├── deployments.ts    # Deployment tools
│   │   └── execution.ts      # Function execution tools
│   │
│   ├── api/
│   │   └── apps-script.ts    # Google Apps Script API wrapper
│   │
│   └── types/
│       └── index.ts          # TypeScript type definitions
│
├── credentials/              # OAuth credentials (gitignored)
│   └── .gitkeep
│
└── docs/
    ├── SETUP.md              # Detailed setup instructions
    ├── AUTHENTICATION.md     # OAuth flow documentation
    └── TOOLS.md              # Tool reference documentation

Implementation Phases

Phase 1: Foundation (Current)

Create project structure
Document goals and architecture
Set up Node.js project with TypeScript
Configure Google Cloud Platform
Implement OAuth2 authentication flow

Phase 2: Core Tools

Implement create_project
Implement get_project and get_content
Implement update_content
Basic error handling and validation

Phase 3: Deployment Tools

Implement create_version
Implement create_deployment
Implement list_deployments
Implement update_deployment

Phase 4: Advanced Features

Implement run_function
Implement get_logs
Add support for bound scripts (Sheets, Docs, Forms)
Comprehensive error handling

Phase 5: Polish & Release

Add comprehensive documentation
Write tests
Create example workflows
Publish to npm (optional)

API Reference

Google Apps Script API Endpoints

Operation	Method	Endpoint
Create Project	POST	`/v1/projects`
Get Project	GET	`/v1/projects/{scriptId}`
Get Content	GET	`/v1/projects/{scriptId}/content`
Update Content	PUT	`/v1/projects/{scriptId}/content`
Create Version	POST	`/v1/projects/{scriptId}/versions`
List Versions	GET	`/v1/projects/{scriptId}/versions`
Create Deployment	POST	`/v1/projects/{scriptId}/deployments`
List Deployments	GET	`/v1/projects/{scriptId}/deployments`
Update Deployment	PUT	`/v1/projects/{scriptId}/deployments/{deploymentId}`
Delete Deployment	DELETE	`/v1/projects/{scriptId}/deployments/{deploymentId}`
Run Function	POST	`/v1/scripts/{scriptId}:run`
Get Metrics	GET	`/v1/projects/{scriptId}/metrics`

Base URL: https://script.googleapis.com

Key Limitations & Considerations

API Limitations

No Service Account Support: The Apps Script API does not work with service accounts - must use OAuth2 with user consent
Full File Replacement: updateContent replaces ALL files - must fetch existing content first, modify, then update
Versioned Deployments: Cannot delete versioned deployments, only archive them
Rate Limits: Subject to Google API quotas

MCP Considerations

Authentication State: Must persist OAuth tokens between sessions
Token Refresh: Handle automatic token refresh
Error Handling: Map Google API errors to meaningful MCP responses

Resources

Official Documentation

Related Tools

clasp (Command Line Apps Script Projects) - Google's official CLI tool
MCP TypeScript SDK

Community

AppsScriptPulse - Community news and updates

Getting Started

Next Step: Continue to Phase 1 Setup - We'll configure the Google Cloud Platform and implement OAuth2 authentication.

License

MIT License - See LICENSE file for details.

Contributing

This is a personal project, but suggestions and feedback are welcome!