Skip to main content
Glama
whichguy

MCP Google Apps Script (GAS) Server

by whichguy
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

MCP Google Apps Script Server

GitHub stars npm version License: MIT Node.js Version TypeScript MCP Protocol

🤖 + 📝 = ⚡

Let AI assistants build and manage Google Apps Script projects for you

🚀 Quick Start • 💡 Use Cases • 🛠️ Features • 📚 Docs

🎯 Why MCP GAS Server?

The Problem

Google Apps Script is powerful for automating Google Workspace, but developing GAS projects traditionally requires:

  • Switching between local development and the online editor

  • Manual copy-pasting of code

  • No proper module system or version control

  • Limited tooling for testing and deployment

The Solution

MCP GAS Server bridges AI assistants with Google Apps Script, enabling:

  • AI-Driven Development: Tell Claude/Cursor what to build, and it handles the implementation

  • Full CommonJS Modules: require(), module.exports, automatic dependency resolution - write GAS like Node.js

  • Ad-hoc Execution: Run any JavaScript expression instantly - no deployment, no wrapper functions needed

  • Production Deployment Pipeline: dev → staging → prod workflow with version control, promotion, and rollback

  • Unix-inspired Interface: Familiar commands (cat, grep, ls, find, sed) for intuitive GAS project management

  • Local Development: Write code locally with full IDE support

  • Automatic Sync: Bidirectional sync between local files and Google's cloud

  • Git Integration: Version control for your GAS projects with safe merging

Who Is This For?

  • Developers who want AI to handle Google Apps Script boilerplate

  • Teams automating Google Workspace workflows

  • Non-programmers who need custom Google Sheets functions or automation

  • Anyone tired of the limitations of Google's online script editor

💡 Use Cases

What You Can Build

  • 📊 Custom Spreadsheet Functions: Complex calculations, data processing, API integrations

  • 📧 Email Automation: Process Gmail, send bulk emails, manage drafts

  • 📅 Calendar Management: Schedule events, sync calendars, automate meeting creation

  • 🗂️ Drive Automation: File organization, backup systems, document generation

  • 📝 Document Processing: Generate reports, merge documents, extract data

  • 🔗 API Integrations: Connect Google Workspace to external services

  • 🤖 Chatbots & Add-ons: Build custom tools for Sheets, Docs, and Forms

Real Examples

// Tell your AI: "Create a function that fetches stock prices and updates my spreadsheet" // AI will create, deploy, and test the entire solution // Tell your AI: "Build an expense tracker that categorizes Gmail receipts" // AI handles OAuth, Gmail API, and spreadsheet integration // Tell your AI: "Make a custom menu in Sheets for data analysis tools" // AI creates the UI, functions, and deploys everything

🚀 Quick Start

⚡ 30-Second Installation

🎯 Fully Automated (Recommended)

curl -fsSL https://raw.githubusercontent.com/whichguy/mcp_gas/main/install.sh | bash -s -- --auto

This single command: downloads → installs dependencies → builds → configures all IDEs

— OR —

🔧 Manual Installation

git clone https://github.com/whichguy/mcp_gas.git && cd mcp_gas && ./install.sh

Clone first, then run installer with more control

Prerequisites

Requirement

Why Needed

How to Get

Auto-Checked?

Git

Clones repository

Download

✅ Yes

Node.js 18+

Runs the MCP server

Download

✅ Yes

Google Account

Access Google Apps Script

Create free

❌ Manual

AI Assistant

Sends commands to server

Claude, Cursor

✅ Detected

🎯 First Project in 2 Minutes

Install (if not already done)

curl -fsSL https://raw.githubusercontent.com/whichguy/mcp_gas/main/install.sh | bash

Tell your AI assistant:

"Create a Google Apps Script project that adds a custom menu to Google Sheets with options to highlight duplicate values and remove empty rows"

AI handles everything:

  • ✅ Creates the project

  • ✅ Writes the code

  • ✅ Sets up the menu

  • ✅ Deploys to Google

  • ✅ Tests the functionality

⚙️ Installation Details

What the Installer Does

The install.sh script handles everything automatically:

  1. 🔄 Downloads Repository (if using curl)

  2. 📦 Installs Dependencies (npm install)

  3. 🔨 Builds Project (npm run build)

  4. 🔍 Detects Your IDEs (checks for 10+ IDEs)

  5. ⚙️ Configures Each IDE (updates MCP settings)

  6. 🔗 Links to (production build)

Features:

  • ✅ Idempotent - Safe to run multiple times

  • 💾 Creates Backups - Before any modifications

  • 🔐 Checks OAuth - Guides you through Google setup

Command-line Options

./install.sh --dry-run # Preview changes without making them ./install.sh --interactive # Choose which IDEs to configure ./install.sh --auto # Non-interactive mode (for CI/CD) ./install.sh --force # Update existing configurations ./install.sh --help # Show detailed usage

Manual Build (Advanced)

If the installer fails or you need custom setup:

# 1. Clone repository git clone https://github.com/whichguy/mcp_gas.git cd mcp_gas # 2. Install dependencies npm install # 3. Build the project npm run build # 4. Configure your IDE manually # Point to: /absolute/path/to/mcp_gas/dist/src/index.js

Note: The server binary is at dist/src/index.js after building, not in the source directory.

Uninstallation

# Remove MCP GAS from all IDEs ./uninstall.sh # With cleanup options: ./uninstall.sh --cleanup-build # Also remove dist/ and node_modules/ ./uninstall.sh --cleanup-backups # Remove all backup files ./uninstall.sh --dry-run # Preview what would be removed

📋 Google Cloud Setup

One-Time Configuration

  1. Enable Google Apps Script API:

    • Visit Google Cloud Console

    • Create or select a project

    • Search for "Google Apps Script API" and enable it

  2. Create OAuth 2.0 Credentials:

    • Navigate to APIs & Services → Credentials

    • Click "Create Credentials" → "OAuth client ID"

    • Application type: Desktop app

    • Download JSON and save as oauth-config.json in project root

🖥️ Supported IDEs

The MCP GAS Server works with any MCP-compatible client:

IDE/Editor

Platform Support

Configuration File

Notes

Claude Desktop

macOS, Windows

claude_desktop_config.json

Official Anthropic desktop app

Claude Code

macOS, Linux

~/.claude/settings.json

Claude's code editor

Cursor IDE

All platforms

~/.cursor/mcp.json

AI-powered IDE

VS Code

All platforms

mcp.json in globalStorage

Microsoft's editor

VS Code Insiders

All platforms

mcp.json in globalStorage

Preview version

VSCodium

All platforms

mcp.json in globalStorage

Open-source VS Code

Zed Editor

macOS, Linux

~/.config/zed/settings.json

Uses context_servers key

Windsurf IDE

All platforms

~/.codeium/windsurf/mcp_config.json

Codeium's AI IDE

Neovim MCPHub

All platforms

~/.config/mcphub/servers.json

Neovim plugin

Codex CLI

All platforms

~/.codex/config.toml

Uses TOML format

Claude Desktop

{ "mcpServers": { "gas": { "command": "node", "args": ["/absolute/path/to/mcp_gas/dist/src/index.js"], "env": {"NODE_ENV": "production"} } } }

VS Code

{ "mcpServers": { "gas": { "command": "node", "args": ["/absolute/path/to/mcp_gas/dist/src/index.js"], "env": {"NODE_ENV": "production"} } } }

Zed Editor (uses context_servers)

{ "context_servers": { "gas": { "command": { "path": "node", "args": ["/absolute/path/to/mcp_gas/dist/src/index.js"] } } } }

Codex CLI (uses TOML)

[mcp_servers.gas] command = "node" args = ["/absolute/path/to/mcp_gas/dist/src/index.js"] [[mcp_servers.gas.env]] NODE_ENV = "production"

📦 What's Included

🛠️ 50 Specialized Tools

📁 File Management

  • ls - List files

  • cat - Read files

  • write - Write files

  • rm - Delete files

  • mv - Move files

  • cp - Copy files

  • mkdir - Create folders

🔍 Search & Edit

  • grep - Search text

  • find - Find files

  • ripgrep - Fast search

  • sed - Find & replace

⚡ Execution

  • run - Run code

  • exec - Execute functions

🔀 Git Integration

  • rsync - Two-phase sync (plan→execute)

  • git_feature - Feature branch management

  • config - Manage sync folder

🚀 Deployment

  • deploy - Unified deployment management (promote/rollback/status/reset)

📋 Projects

  • project_create - New project

  • project_set - Set current

  • project_list - List all

Smart vs Raw Tools

  • Smart tools (cat, write): Automatically handle CommonJS module wrapping

  • Raw tools (raw_cat, raw_write): Preserve exact file content

  • Choose based on whether you want automatic module management or full control

🎓 When to Use MCP GAS Server

✅ Perfect For

  • Automation Projects: Gmail, Calendar, Drive, Sheets automation

  • Custom Functions: Complex spreadsheet formulas and data processing

  • API Integrations: Connecting Google Workspace to external services

  • Rapid Prototyping: Quick proof-of-concepts and MVPs

  • Learning GAS: Let AI teach by example

❌ Not Ideal For

  • Large Applications: Consider App Engine or Cloud Functions for complex apps

  • Real-time Systems: GAS has execution time limits (6 minutes)

  • Heavy Computing: Limited CPU/memory compared to dedicated servers

  • Sensitive Data: Evaluate security requirements carefully

🛠️ Advanced Features

Git Workflow Integration

// Set up .git/config breadcrumb file first mcp__gas__write({ scriptId: "...", path: ".git/config", content: JSON.stringify({ repository: "https://github.com/...", localPath: "~/my-project" }) }) // Two-phase sync: plan then execute mcp__gas__rsync({ operation: "plan", scriptId: "...", direction: "pull" }) mcp__gas__rsync({ operation: "execute", scriptId: "...", planId: "..." }) // Standard git workflow works in sync folder cd ~/gas-repos/project-xxx git add . && git commit -m "Update" && git push

Module System

// Write modular code with CommonJS const utils = require('./utils'); const api = require('./api/client'); function processData() { const data = api.fetchData(); return utils.transform(data); } module.exports = { processData };

First Project Example

// Tell your AI assistant: "Create a Google Apps Script project that calculates Fibonacci numbers" // The AI will execute: // 1. Authenticate await mcp__gas__auth({ mode: "start" }); // 2. Create project const project = await mcp__gas__project_create({ title: "Fibonacci Calculator" }); // 3. Add code await mcp__gas__write({ scriptId: project.scriptId, path: "fibonacci", content: ` function fibonacci(n) { if (n <= 1) return n; return fibonacci(n - 1) + fibonacci(n - 2); } function test() { Logger.log(fibonacci(10)); // 55 } module.exports = { fibonacci }; ` }); // 4. Execute const result = await mcp__gas__run({ scriptId: project.scriptId, js_statement: "require('fibonacci').fibonacci(10)" }); // Returns: 55

📚 Quick Command Reference

Filesystem Operations (Unix-inspired)

// Read file contents (auto-unwraps CommonJS) mcp__gas__cat({ scriptId: "...", path: "utils/helper" }) // List files matching pattern mcp__gas__ls({ scriptId: "...", path: "utils/*" }) // ⚡ RECOMMENDED: High-performance multi-pattern search with ripgrep mcp__gas__ripgrep({ scriptId: "...", pattern: "function.*test", ignoreCase: true, context: 2 }) // Simple grep (use ripgrep for advanced searches) mcp__gas__grep({ scriptId: "...", pattern: "function.*test", outputMode: "content" }) // Find files by name pattern mcp__gas__find({ scriptId: "...", name: "*.test" }) // Find/replace with regex mcp__gas__sed({ scriptId: "...", pattern: "console\\.log", replacement: "Logger.log" }) // ⚡ Advanced ripgrep features (STRONGLY RECOMMENDED over grep) mcp__gas__ripgrep({ scriptId: "...", pattern: "TODO|FIXME|HACK", // Multi-pattern OR search ignoreCase: true, // Case-insensitive sort: "path", // Alphabetical sorting trim: true, // Clean whitespace context: 2, // Show 2 lines of context showStats: true // Performance statistics })

Ad-hoc Code Execution

// Execute mathematical expressions mcp__gas__run({ scriptId: "...", js_statement: "Math.PI * 2" }) // Call Google Apps Script services mcp__gas__run({ scriptId: "...", js_statement: "DriveApp.getRootFolder().getName()" }) // Execute project functions with CommonJS mcp__gas__run({ scriptId: "...", js_statement: "require('Calculator').fibonacci(10)" }) // Complex data operations mcp__gas__run({ scriptId: "...", js_statement: ` const data = require('API').fetchData(); const sheet = SpreadsheetApp.create('Report'); sheet.getActiveSheet().getRange(1,1,data.length,3).setValues(data); return sheet.getId(); ` })

CommonJS Module Development

// Write module with automatic CommonJS wrapping mcp__gas__write({ scriptId: "...", path: "Calculator", content: ` function add(a, b) { return a + b; } function multiply(a, b) { return a * b; } module.exports = { add, multiply }; ` }) // Use require() in other modules - automatic dependency resolution mcp__gas__write({ scriptId: "...", path: "Main", content: ` const calc = require('Calculator'); const result = calc.add(5, calc.multiply(2, 3)); Logger.log(result); // Logs: 11 ` }) // Read shows clean user code (CommonJS wrapper removed) mcp__gas__cat({ scriptId: "...", path: "Calculator" }) // Returns user code without _main() wrapper

Git Integration

// Create .git/config breadcrumb file mcp__gas__write({ scriptId: "...", path: ".git/config", content: JSON.stringify({ repository: "https://github.com/owner/repo.git", localPath: "~/my-projects/gas-app" }) }) // Two-phase sync: plan then execute mcp__gas__rsync({ operation: "plan", scriptId: "...", direction: "pull" }) mcp__gas__rsync({ operation: "execute", scriptId: "...", planId: "..." }) // Manage sync folder configuration mcp__gas__config({ operation: "set", setting: "sync_folder", scriptId: "...", value: "~/my-projects/gas-app" })

🔧 Troubleshooting

Common Issues

Problem

Solution

"Not authenticated"

Run mcp__gas__auth({ mode: "start" }) in your AI assistant

"Script not found"

Check scriptId in gas-config.json

"Module not found"

Ensure proper require() paths and file exists

"Quota exceeded"

Wait or upgrade Google Cloud quotas

"Permission denied"

Check OAuth scopes and project permissions

Debug Mode

# Enable debug logging DEBUG=mcp:* npm start # Test installation without changes ./install.sh --dry-run # Check configuration cat ~/.claude/claude_desktop_config.json | jq '.mcpServers.gas'

📂 Project Structure

mcp_gas/ ├── src/ # TypeScript source code │ ├── tools/ # ~50 MCP tools │ ├── auth/ # OAuth authentication │ ├── api/ # Google Apps Script API client │ └── server/ # MCP server implementation ├── dist/ # Compiled JavaScript (after build) ├── test/ # Test suites ├── docs/ # Documentation ├── install.sh # Automated installer ├── uninstall.sh # Clean uninstaller ├── gas-config.json # Project configuration └── oauth-config.json # OAuth credentials (create this)

🧪 Development

Setup

# Clone and install git clone https://github.com/whichguy/mcp_gas.git cd mcp_gas npm install # Development mode with watch npm run dev # Build for production npm run build

Testing

npm test # Run all tests npm run test:unit # Unit tests only npm run test:integration # Integration tests (requires auth) npm run test:system # System-level tests npm run test:security # Security validation

Architecture

The MCP GAS Server uses a layered architecture:

  1. MCP Protocol Layer: Handles communication with AI assistants

  2. Tool Layer: ~50 specialized tools for GAS operations

  3. Authentication Layer: OAuth 2.0 PKCE flow with token management

  4. API Client Layer: Google Apps Script API v1 client with rate limiting

  5. File System Layer: Local caching and synchronization

📚 Documentation

Complete Tool Reference

  • docs/REFERENCE.md - Complete reference for all 63 tools with capabilities, limitations, and compatibility matrix

Developer Guides

Enhanced Tool Schemas

All tools now include:

  • Script Type Compatibility - Clear indication of standalone vs container-bound support

  • Limitations - Specific constraints, quotas, and API restrictions

  • Cross-Tool References - Prerequisites, next steps, alternatives, and error recovery guidance

  • ⚡ Search Tool Preference - ripgrep is STRONGLY RECOMMENDED over grep for all searches (multi-pattern, smart case, context control, better performance)

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

📄 License

MIT - See LICENSE for details.

🙏 Acknowledgments

Built on:

🌟 Ready to supercharge your Google Apps Script development?

Made with ❤️ by the MCP GAS community

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/whichguy/gas_mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server