whichguy/gas_mcp
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.
MCP Google Apps Script Server
๐ค + ๐ = โก
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
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.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 |
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
|
๐ 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
// 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
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/ # 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:
- MCP Protocol Layer: Handles communication with AI assistants
- Tool Layer: 46 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
- - 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.
- ๐ Report bugs
- ๐ก Request features
- ๐ Improve documentation
- ๐ง Submit pull requests
๐ License
MIT - See for details.
๐ Acknowledgments
Built on:
- Model Context Protocol by Anthropic
- Google Apps Script API
- TypeScript, Node.js, and the amazing open-source community