gas_mcp

whichguy/gas_mcp

3.3

If you are the rightful owner of gas_mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The MCP Google Apps Script Server is a robust server designed to integrate AI assistants with Google Apps Script, enabling seamless project management and execution.

Tools
5
Resources
0
Prompts
0

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
  • 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

RequirementWhy NeededHow to GetAuto-Checked?
GitClones repositoryDownloadโœ… Yes
Node.js 18+Runs the MCP serverDownloadโœ… Yes
Google AccountAccess Google Apps ScriptCreate freeโŒ Manual
AI AssistantSends commands to serverClaude, Cursorโœ… Detected

๐ŸŽฏ First Project in 2 Minutes

1๏ธโƒฃ

Install (if not already done)

curl -fsSL https://raw.githubusercontent.com/whichguy/mcp_gas/main/install.sh | bash
2๏ธโƒฃ

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"

3๏ธโƒฃ

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 dist/src/index.js (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/EditorPlatform SupportConfiguration FileNotes
Claude DesktopmacOS, Windowsclaude_desktop_config.jsonOfficial Anthropic desktop app
Claude CodemacOS, Linux~/.claude/settings.jsonClaude's code editor
Cursor IDEAll platforms~/.cursor/mcp.jsonAI-powered IDE
VS CodeAll platformsmcp.json in globalStorageMicrosoft's editor
VS Code InsidersAll platformsmcp.json in globalStoragePreview version
VSCodiumAll platformsmcp.json in globalStorageOpen-source VS Code
Zed EditormacOS, Linux~/.config/zed/settings.jsonUses context_servers key
Windsurf IDEAll platforms~/.codeium/windsurf/mcp_config.jsonCodeium's AI IDE
Neovim MCPHubAll platforms~/.config/mcphub/servers.jsonNeovim plugin
Codex CLIAll platforms~/.codex/config.tomlUses TOML format
Manual IDE Configuration Examples

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

๐Ÿ› ๏ธ 46 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

  • git_init - Initialize repo
  • git_sync - Sync changes
  • git_status - Check status

๐Ÿš€ Deployment

  • deploy_create - Deploy apps
  • version_create - Create versions

๐Ÿ“‹ 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

// Initialize git for a GAS project
mcp__gas__git_init({ scriptId: "...", repository: "https://github.com/..." })

// Sync changes (always safe - pulls, merges, then pushes)
mcp__gas__git_sync({ scriptId: "..." })

// 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

// Initialize git association with .git.gs marker
mcp__gas__git_init({
  scriptId: "...",
  repository: "https://github.com/owner/repo.git"
})

// Safe pull-merge-push synchronization (ALWAYS pulls first)
mcp__gas__git_sync({ scriptId: "..." })

// Check git status and sync folder location
mcp__gas__git_status({ scriptId: "..." })

// Set local sync folder for git operations
mcp__gas__git_set_sync_folder({
  scriptId: "...",
  localPath: "~/my-projects/gas-app"
})

๐Ÿ”ง Troubleshooting

Common Issues

ProblemSolution
"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/              # All 46 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: 46 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

  • - Complete reference for all 63 tools with capabilities, limitations, and compatibility matrix

Developer Guides

  • - Strategy for cross-tool references and workflow chaining
  • - Progress tracking for schema improvements
  • - System design and internals
  • - Version control workflows
  • - TypeScript API reference
  • - Sample projects and use cases

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 for guidelines.

๐Ÿ“„ License

MIT - See for details.

๐Ÿ™ Acknowledgments

Built on:


๐ŸŒŸ Ready to supercharge your Google Apps Script development?


ย ย  ย ย 



Made with โค๏ธ by the MCP GAS community