MCP Google Apps Script (GAS) Server

MCP谷歌应用脚本服务器

](https://www.npmjs.com/package/gas-server)  ](https://nodejs.org/)  

🤖 + 📝 = ⚡

让AI助手为您构建和管理Google Apps Script项目

🚀 快速开始 • 💡 用例 • 🛠️ 特性 • 📚 文档

______________________________________________________________________

🎯 为什么选择MCP GAS服务器？

问题

Google Apps Script在自动化Google Workspace方面功能强大，但开发GAS项目传统上需要：

• 在本地开发和在线编辑器之间切换
• 手动复制粘贴代码
• 没有适当的模块系统或版本控制
• 测试和部署工具有限

解决方案

MCP GAS服务器将AI助手与Google Apps脚本连接起来，实现：

• AI驱动开发：告诉Claude/Cursor要构建什么，它将处理实现
• 完整的CommonJS模块: require(), module.exports，自动依赖解析-像Node.js一样编写GAS
• 临时执行：立即运行任何JavaScript表达式-无需部署，无需包装器函数
• 生产部署管道：dev→ 暂存→ 带有版本控制、升级和回滚的prod工作流
• Unix风格的界面：熟悉的命令(cat, grep, ls, find, sed)用于直观的GAS项目管理
• 本地开发：使用完整的IDE支持在本地编写代码
• 自动同步：本地文件和谷歌云之间的双向同步
• Git集成：通过安全合并对GAS项目进行版本控制

这是给谁的？

• 开发者 谁希望人工智能处理谷歌应用程序脚本样板
• 团队 自动化谷歌工作区工作流程
• 非程序员 谁需要自定义Google表格功能或自动化
• 任何人 厌倦了谷歌在线脚本编辑器的局限性

💡 用例

你能建造什么

• 📊 自定义电子表格功能：复杂的计算、数据处理、API集成
• 📧 邮件自动化：处理Gmail、发送批量电子邮件、管理草稿
• 📅 日历管理：安排事件、同步日历、自动创建会议
• 🗂️ 驱动自动化：文件组织、备份系统、文档生成
• 📝 文档处理：生成报告、合并文档、提取数据
• 🔗 API集成：将Google Workspace连接到外部服务
• 🤖 聊天机器人和附加组件：为图纸、文档和表单构建自定义工具

真实案例

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

🚀 快速开始

⚡ 30秒安装

🎯 全自动（推荐）

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

*这个命令：下载→ 安装依赖项→ 构建→ 配置所有IDE*

--或--

🔧 手动安装

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

*先克隆，然后运行具有更多控制权的安装程序*

先决条件

🎯 2分钟内的第一个项目

1️⃣

安装 （如果尚未完成）

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

2️⃣

告诉你的AI助手：

“创建一个Google Apps脚本项目，为Google表格添加自定义菜单 具有突出显示重复值和删除空行的选项”

3️⃣

AI处理一切：

• ✅ 创建项目
• ✅ 写入代码
• ✅ 设置菜单
• ✅ 部署到Google
• ✅ 测试功能

⚙️ 安装详情

安装程序做什么

这 install.sh 脚本自动处理一切：

1. 🔄 下载存储库 （如果使用curl）
2. 📦 安装依赖项 (npm install)
3. 🔨 建设项目 (npm run build)
4. 🔍 检测您的IDE （检查10+IDE）
5. ⚙️ 配置每个IDE （更新MCP设置）
6. 🔗 链接到 dist/src/index.js （生产建设）

特征：

• ✅ 幂等 -多次运行安全
• 💾 创建备份 -在进行任何修改之前
• 🔐 检查OAuth -指导您完成Google设置

命令行选项

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

手动构建（高级）

如果安装程序失败或您需要自定义设置：

# 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

备注：服务器二进制文件位于 dist/src/index.js 构建后，不在源目录中。

卸载

# 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

📋 谷歌云设置

一次性配置

1. 启用Google应用程序脚本API:

- 访问 谷歌云控制台 - 创建或选择项目 - 搜索“Google应用程序脚本API”并启用它

1. 创建OAuth 2.0凭据:

- 导航到API和服务→ 凭证 - 点击“创建凭据”→ “OAuth客户端ID” - 应用程序类型： 桌面应用程序 - 下载JSON并另存为 oauth-config.json 在项目根中

🖥️ 支持的IDE

MCP GAS服务器可与任何兼容MCP的客户端配合使用：

Manual IDE Configuration Examples

克劳德桌面版

{
  "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编辑器（使用 context_servers)

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

Codex CLI（使用TOML）

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

[[mcp_servers.gas.env]]
NODE_ENV = "production"

📦 包含什么

🛠️ 50种专用工具

📁 文件管理

• ls -列出文件
• cat -读取文件
• write -写入文件
• rm -删除文件
• mv -移动文件
• cp -复制文件
• mkdir -创建文件夹

🔍 搜索和编辑

• grep -搜索文本
• find -查找文件
• ripgrep -快速搜索
• sed -查找并替换

⚡ 执行

• run -运行代码
• exec -执行功能

🔀 Git集成

• rsync -无状态同步（使用dryrun进行拉/推）
• git_feature -功能分支管理
• config -管理同步文件夹

🚀 部署

• deploy -统一部署管理（升级/回滚/状态/重置）

📋 项目

• project_create -新项目
• project_set -设置电流
• project_list -列出全部

智能工具与原始工具

• 智能工具 (cat, write)：自动处理CommonJS模块包装
• 原始工具 (raw_cat, raw_write)：保留确切的文件内容
• 根据您想要自动模块管理还是完全控制进行选择

🎓 何时使用MCP GAS服务器

✅ 非常适合

• 自动化项目：Gmail、日历、驱动器、表格自动化
• 自定义函数：复杂的电子表格公式和数据处理
• API集成：将Google Workspace连接到外部服务
• 快速原型制作：概念和MVP的快速证明
• 学习GAS：让AI以身作则

❌ 不适合

• 大型应用：对于复杂的应用程序，考虑应用引擎或云功能
• 实时系统：GAS有执行时间限制（6分钟）
• 繁重的计算：与专用服务器相比，CPU/内存有限
• 敏感数据：仔细评估安全要求

🛠️ 高级功能

Git工作流集成

// Set up .git/config breadcrumb file first
mcp__gas__write({
  scriptId: "...",
  path: ".git/config",
  content: JSON.stringify({ repository: "https://github.com/...", localPath: "~/my-project" })
})

// Stateless sync: preview then apply
mcp__gas__rsync({ operation: "pull", scriptId: "...", dryrun: true })
mcp__gas__rsync({ operation: "pull", scriptId: "..." })

// Standard git workflow works in sync folder
cd ~/gas-repos/project-xxx
git add . && git commit -m "Update" && git push

模块系统

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

第一个项目示例

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

📚 快速命令参考

文件系统操作（受Unix启发）

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

特殊代码执行

// 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模块开发

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

// 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"
  })
})

// Stateless sync: preview then apply
mcp__gas__rsync({ operation: "pull", scriptId: "...", dryrun: true })
mcp__gas__rsync({ operation: "pull", scriptId: "..." })

// Manage sync folder configuration
mcp__gas__config({
  operation: "set",
  setting: "sync_folder",
  scriptId: "...",
  value: "~/my-projects/gas-app"
})

🔧 故障排除

常见问题

调试模式

# 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'

📂 项目结构

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)

🧪 发展

设置

# 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

测试

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

建筑

MCP GAS服务器使用分层架构：

1. MCP协议层：处理与AI助手的通信
2. 工具层：约50个GAS操作专用工具
3. 认证层：OAuth 2.0具有令牌管理的PKCE流
4. API客户端层：Google Apps脚本API v1客户端，具有速率限制
5. 系统层：本地缓存和同步

📚 文档

完整的工具参考

• 文档/参考.md -所有63个工具的完整参考，包括功能、限制和兼容性矩阵

开发者指南

• docs/CROSS_TOOL_REFERENCES.md -跨工具引用和工作流链策略
• docs/SCHEMA_增强功能_SUMMARY.md -模式改进的进度跟踪
• 架构指南 -系统设计和内部构件
• Git集成 -版本控制工作流
• API 文档 -TypeScript API引用
• 例子 -示例项目和用例

增强的工具模式

所有工具现在包括：

• 脚本类型兼容性 -明确指出独立支持与容器绑定支持
• 局限性 -具体限制、配额和API限制
• 交叉工具参考 -先决条件、下一步、替代方案和错误恢复指南
• ⚡ 搜索工具首选项 - 强烈建议使用ripgrep 所有搜索都优于grep（多模式、智能案例、上下文控制、更好的性能）

🤝 贡献

我们欢迎捐款！看 贡献.md 作为指导方针。

• 🐛 报告错误
• 💡 请求功能
• 📖 改进文档
• 🔧 提交拉取请求

📄 许可证

麻省理工学院-参见 许可证 了解详情。

🙏 致谢

构建于：

• 模型上下文协议 通过Anthropic
• 谷歌应用程序脚本API
• TypeScript、Node.js和令人惊叹的开源社区

______________________________________________________________________

🌟 准备好为您的Google Apps脚本开发注入活力了吗？

由...制作❤️ MCP GAS社区