MCP Google Apps Script Server
🤖 + 📝 = ⚡
Let AI assistants build and manage Google Apps Script projects for you
🎯 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
| 1️⃣ |
Install (if not already done) |
| 2️⃣ |
Tell your AI assistant:
|
| 3️⃣ |
AI handles everything:
|
⚙️ Installation Details
What the Installer Does
The install.sh script handles everything automatically:
- 🔄 Downloads Repository (if using curl)
- 📦 Installs Dependencies (
npm install) - 🔨 Builds Project (
npm run build) - 🔍 Detects Your IDEs (checks for 10+ IDEs)
- ⚙️ Configures Each IDE (updates MCP settings)
- 🔗 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
-
Enable Google Apps Script API:
- Visit Google Cloud Console
- Create or select a project
- Search for "Google Apps Script API" and enable it
-
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.jsonin 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 |
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
🛠️ 50 Specialized Tools
|
📁 File Management
|
🔍 Search & Edit
|
⚡ Execution
|
|
🔀 Git Integration
|
🚀 Deployment
|
📋 Projects
|
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:
- MCP Protocol Layer: Handles communication with AI assistants
- Tool Layer: ~50 specialized tools for GAS operations
- Authentication Layer: OAuth 2.0 PKCE flow with token management
- API Client Layer: Google Apps Script API v1 client with rate limiting
- 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
- docs/CROSS_TOOL_REFERENCES.md - Strategy for cross-tool references and workflow chaining
- docs/SCHEMA_ENHANCEMENTS_SUMMARY.md - Progress tracking for schema improvements
- Architecture Guide - System design and internals
- Git Integration - Version control workflows
- API Documentation - TypeScript API reference
- Examples - 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 CONTRIBUTING.md for guidelines.
📄 License
MIT - See LICENSE for details.
🙏 Acknowledgments
Built on:
- Model Context Protocol by Anthropic
- Google Apps Script API
- TypeScript, Node.js, and the amazing open-source community
🌟 Ready to supercharge your Google Apps Script development?
Made with ❤️ by the MCP GAS community