](https://mseep.ai/app/mohalmah-google-appscript-mcp-server)

谷歌应用程序脚本MCP服务器

](https://smithery.ai/server/@mohalmah/google-appscript-mcp-server)

作者: 穆罕默德\ 许可证：MIT许可证\ 仓库: 谷歌应用程序脚本mcp服务器

欢迎来到Google Apps脚本MCP（模型上下文协议）服务器！ 🚀

此MCP服务器提供与Google Apps Script API的全面集成，允许您通过任何兼容MCP的客户端（如Claude Desktop、VS Code with Cline或Postman）管理脚本项目、部署、版本和执行。

🌟 概述

此MCP服务器通过以下方式实现与Google Apps Script的无缝交互：

✅ OAuth 2.0身份验证 -具有自动刷新功能的安全令牌管理
✅ 16个综合工具 -完整的Google应用程序脚本API覆盖范围
✅ MCP协议合规性 -适用于Claude Desktop、VS Code和其他MCP客户端
✅ 安全令牌存储 -用于刷新令牌的特定于操作系统的安全存储
✅ 自动令牌刷新 -自动处理令牌过期
✅ 详细日志记录 -全面的错误处理和调试

🎥 演示视频

Google Apps Script MCP Server Demo

*观看Google Apps脚本MCP服务器的运行情况——通过VS Code AI Agent创建项目、管理部署和执行脚本。*

🚀 特性

核心能力

项目管理：创建、检索和更新Google Apps脚本项目
部署管理：创建、列出、更新和删除脚本部署
版本控制：创建和管理脚本版本
内容管理：获取和更新脚本内容和文件
过程监控：列出并监视脚本执行过程
指标访问：检索脚本执行指标和分析
脚本执行：远程运行Google Apps脚本函数

安全功能

OAuth 2.0流程：完整的Google OAuth实现
安全令牌存储：刷新存储在操作系统密钥链/凭据管理器中的令牌
自动令牌刷新：不需要手动令牌管理
环境变量支持：安全凭据配置

⚙️ 先决条件

在开始之前，请确保您已经：

Node.js （要求v18+，建议v20+）- 点击此处下载
npm （包含在Node.js中）
Google账户 可以访问谷歌云控制台
Git （用于克隆存储库）

🚀 快速入门指南

1.克隆存储库

git clone https://github.com/mohalmah/google-apps-script-mcp-server.git
cd google-apps-script-mcp-server

2.安装依赖项

npm install

3.设置谷歌云OAuth

跟随详细的OAuth设置指南在......下面

4.运行OAuth安装程序

npm run setup-oauth

5.测试服务器

npm start

1.1 Node.js的MCP配置

编辑您的 claude_desktop_config.json 文件：

视窗: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "google-apps-script": {
      "command": "node",
      "args": ["/path/to/google-appscript-mcp-server/mcpServer.js"],
      "env": {
        "GOOGLE_APP_SCRIPT_API_CLIENT_ID": "your_client_id",
        "GOOGLE_APP_SCRIPT_API_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

1.2 Docker的MCP配置

构建Docker镜像：

docker build -t google-appscript-mcp:latest .

编辑您的 claude_desktop_config.json 文件：

{
  "mcpServers": {
    "google-apps-script": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "GOOGLE_APP_SCRIPT_API_CLIENT_ID=your_client_id",
        "-e", "GOOGLE_APP_SCRIPT_API_CLIENT_SECRET=your_client_secret",
        "-v", "google-appscript-tokens:/home/app/.config/google-apps-script-mcp",
        "google-appscript-mcp:latest"
      ]
    }
  }
}

📖 详细的设置说明

如果您尚未克隆存储库并安装依赖项，请按照以下步骤操作快速入门指南第一。

步骤1:谷歌云控制台设置

1.1创建或选择谷歌云项目

首选谷歌云控制台
单击顶部的项目下拉列表
点击 “新项目” 或选择一个现有项目
如果创建新：

- 输入项目名称（例如，“Google Apps脚本MCP”） - 记下你的项目ID（你需要这个） - 点击 “创建”

1.2启用所需的API

在Google Cloud控制台中，导航到 API和服务 → 图书馆
搜索并启用以下API：

- 谷歌应用程序脚本API （必填） - Google Drive API （建议用于文件访问） - 谷歌云资源管理器API （用于项目运营）

对于Google应用程序脚本API：

搜索“Google应用程序脚本API”
点击结果
点击 “启用”
等待API启用（可能需要几分钟时间）

1.3配置OAuth同意屏幕

首选 API和服务 → OAuth同意屏幕
选择外部（除非您在Google Workspace组织中）
填写所需信息：

- 应用程序名称：“谷歌应用程序脚本MCP服务器” - 用户支持电子邮件：您的电子邮件地址 - 应用程序徽标：（可选） - 应用领域：留白待开发 - 开发人员联系信息：您的电子邮件地址

点击 “保存并继续”

配置作用域（可选但推荐）：

点击 “添加或删除范围”
添加以下范围：

- https://www.googleapis.com/auth/script.projects - https://www.googleapis.com/auth/script.projects.readonly - https://www.googleapis.com/auth/script.deployments - https://www.googleapis.com/auth/script.deployments.readonly - https://www.googleapis.com/auth/script.metrics - https://www.googleapis.com/auth/script.processes

点击 “更新”

添加测试用户（适用于外部应用程序）：

点击 “添加用户”
将您的Gmail地址添加为测试用户
点击 “保存并继续”

1.4创建OAuth 2.0凭据

首选 API和服务 → 凭证
点击 “+创建凭据” → “OAuth 2.0客户端ID”
对于“应用程序类型”，选择 “Web应用程序”
配置客户端：

- 名称：“谷歌应用程序脚本MCP客户端” - 授权的JavaScript来源：（暂时留空） - 授权重定向URI：精确添加以下URL：

     http://localhost:3001/oauth/callback

点击 “创建”
重要：复制您的 客户端ID 和 客户端密钥 立即

- 客户端ID看起来像： 1234567890-abcdefghijklmnop.apps.googleusercontent.com - 客户端密码看起来像： GOCSPX-abcdefghijklmnopqrstuvwxyz

步骤2：配置环境变量

2.1创建.env文件

创建一个 .env 项目根目录中的文件：

# On Windows
type nul > .env

# On macOS/Linux
touch .env

2.2添加OAuth凭据

编辑 .env 文件并添加您的凭据：

# Google Apps Script API OAuth Configuration
GOOGLE_APP_SCRIPT_API_CLIENT_ID=your_client_id_here
GOOGLE_APP_SCRIPT_API_CLIENT_SECRET=your_client_secret_here

# Optional: Logging level
LOG_LEVEL=info

用实际值替换占位符：

替换 your_client_id_here 使用您的客户ID
替换 your_client_secret_here 使用您的客户机密

步骤3:OAuth身份验证设置

3.1运行OAuth安装程序

执行OAuth设置脚本：

npm run setup-oauth

这有什么作用：

在上启动临时本地服务器 http://localhost:3001
打开默认浏览器，进入谷歌的授权页面
要求您授予应用程序权限
通过回调URL捕获授权码
交换访问和刷新令牌的代码
将刷新令牌安全地存储在操作系统凭据存储中
通过进行测试API调用来测试令牌

3.2授予权限

当您的浏览器打开时：

选择您的Google帐户 （必须是您添加的测试用户）
查看权限 被请求：

- 查看和管理您的Google Apps脚本项目 - 查看您的脚本执行和指标 - 访问您的脚本部署

点击“继续” 或 “允许”
你应该看看：“OAuth安装已成功完成！”

3.3验证令牌存储

设置过程安全地存储令牌：

视窗：Windows凭据管理器
macOS：钥匙链访问
Linux：特勤局API（GNOME钥匙圈/KDE钱包）

步骤4：测试您的设置

4.1测试MCP服务器

npm start

您应该看到如下输出：

Google Apps Script MCP Server running on stdio
OAuth tokens loaded successfully
Server ready to handle MCP requests

4.2使用可用命令进行测试

# List all available tools
npm run list-tools

# Test OAuth connection
npm run test-oauth

# Enable debug logging
npm run debug

🛠️ 可用工具

此MCP服务器为Google Apps脚本管理提供了16个全面的工具：

项目管理工具

1. `script-projects-create`

目的：创建新的Google Apps脚本项目参数:

title （必填）：新脚本项目的标题
parentId （可选）：父项目的ID

示例用法：为自动化任务创建新脚本

// Creates: "My Automation Script" project
{
  "title": "My Automation Script",
  "parentId": "1234567890"
}

2. `script-projects-get`

目的：获取Google Apps Script项目的元数据参数:

scriptId （必填）：要检索的脚本项目的ID
fields （可选）：响应中要包含的特定字段
alt （可选）：响应的数据格式（默认：“json”）

示例用法：检索项目信息

// Gets project details for script ID
{
  "scriptId": "1ABC123def456GHI789jkl"
}

3. `script-projects-get-content`

目的：获取Google Apps Script项目的内容参数:

scriptId （必填）：脚本项目的ID
versionNumber （可选）：要检索的特定版本号

它返回什么：项目中的完整源代码和文件 示例用法：下载脚本源代码以进行备份或分析

4. `script-projects-update-content`

目的：更新Google Apps Script项目的内容参数:

scriptId （必填）：要更新的脚本项目的ID
files （必需）：包含名称、类型和源的文件对象数组

示例用法：将代码更改部署到脚本项目

版本管理工具

5. `script-projects-versions-create`

目的：创建Google Apps Script项目的新版本参数:

scriptId （必填）：脚本项目的ID
description （必填）：新版本说明

示例用法：创建版本化快照以进行部署

{
  "scriptId": "1ABC123def456GHI789jkl",
  "description": "Added email notification feature"
}

6. `script-projects-versions-get`

目的：获取特定脚本版本的详细信息参数:

scriptId （必填）：脚本项目的ID
versionNumber （必填）：要检索的版本号

7. `script-projects-versions-list`

目的：列出脚本项目的所有版本参数:

scriptId （必填）：脚本项目的ID
pageSize （可选）：每页的版本数
pageToken （可选）：分页标记

部署管理工具

8. `script-projects-deployments-create`

目的：创建Google Apps Script项目的部署参数:

scriptId （必填）：要部署的脚本的ID
versionNumber （必需）：要部署的版本号
manifestFileName （必填）：清单文件的名称
description （必填）：部署说明

示例用法：将脚本部署为web应用程序或API可执行文件

{
  "scriptId": "1ABC123def456GHI789jkl",
  "versionNumber": 3,
  "manifestFileName": "appsscript.json",
  "description": "Production deployment v1.2"
}

备注：如果您的部署使用谷歌服务，例如 DriveApp 或 SpreadsheetApp，您必须在应用程序脚本编辑器中手动授权脚本，然后web应用程序才会响应。看脚本授权.

9. `script-projects-deployments-get`

目的：获取特定部署的详细信息参数:

scriptId （必填）：脚本项目的ID
deploymentId （必填）：部署的ID

10. `script-projects-deployments-list`

目的：列出脚本项目的所有部署参数:

scriptId （必填）：脚本项目的ID
pageSize （可选）：每页部署的数量

11. `script-projects-deployments-update`

目的：更新现有部署参数:

scriptId （必填）：脚本项目的ID
deploymentId （必需）：要更新的部署的ID
deploymentConfig （必需）：新的部署配置

12. `script-projects-deployments-delete`

目的：删除部署参数:

scriptId （必填）：脚本项目的ID
deploymentId （必填）：要删除的部署的ID

执行和监控工具

13. `script-scripts-run`

目的：执行Google Apps脚本函数参数:

scriptId （必填）：要运行的脚本的ID
特定于正在执行的函数的其他参数

示例用法：远程触发脚本执行备注：必须部署脚本，并且您必须具有执行权限

14. `script-processes-list`

目的：列出脚本项目的执行过程参数:

scriptId （必填）：脚本项目的ID
pageSize （可选）：每页进程数
pageToken （可选）：分页标记
statuses （可选）：按流程状态筛选
types （可选）：按流程类型筛选
functionName （可选）：按函数名称筛选
startTime （可选）：按开始时间筛选
endTime （可选）：按结束时间过滤

它显示了什么：正在运行、已完成和失败的脚本执行

15. `script-processes-list-script-processes`

目的：列出具有额外筛选的脚本进程的替代方法参数：类似于 script-processes-list 具有增强的过滤选项

16. `script-projects-get-metrics`

目的：获取脚本项目的执行指标和分析参数:

scriptId （必填）：脚本项目的ID
deploymentId （必填）：部署的ID
metricsGranularity （必填）：度量数据的粒度
fields （必填）：要检索的特定度量字段

它提供了什么:

执行计数
错误率
性能指标
使用情况分析

工具类别摘要

类别	工具	目的
项目管理	创建、获取、获取内容、更新内容	管理脚本项目和源代码
版本控制	版本创建、版本获取、版本列表	处理脚本版本控制
部署	部署创建、部署获取、部署列表、部署更新、部署删除	管理脚本部署
执行	脚本运行	执行脚本函数
监控	流程列表，获取指标	监控执行和性能

常见用例

开发工作流程:

使用 script-projects-create 创建新项目
使用 script-projects-update-content 上传代码
使用 script-projects-versions-create 创建稳定版本
使用 script-projects-deployments-create 部署到生产环境

监控与调试:

使用 script-processes-list 查看执行历史记录
使用 script-projects-get-metrics 分析性能
使用 script-projects-get-content 备份源代码

生产管理:

使用 script-projects-deployments-list 查看所有部署
使用 script-projects-deployments-update 更新生产配置
使用 script-scripts-run 触发自动化工作流程

⚠️ 脚本授权

当脚本使用谷歌服务时，例如 DriveApp, SpreadsheetApp, GmailApp，或 CalendarApp，必须手动授权，部署的web应用程序才能正确响应。MCP服务器的API部署不触发谷歌的OAuth同意流。

如果您部署的web应用程序返回“拒绝访问”或“您需要访问”，部署后完成这些步骤一次：

在应用程序脚本编辑器中打开脚本：

   https://script.google.com/d/{SCRIPT_ID}/edit

*（替换 {SCRIPT_ID} ID由返回 script-projects-create 或 script-projects-get.)*

点击跑在调用谷歌服务的任何功能上（例如。， doGet).

出现提示时，单击 查看权限.

完成Google OAuth同意流程：

- 选择您的Google帐户 - 点击高级 → 转到｛项目名称｝（不安全） - 点击允许

您部署的web应用程序现在将正常工作。

注：这是谷歌应用程序脚本平台的要求，不能通过API绕过。

🌐 使用Postman测试MCP服务器

MCP服务器(mcpServer.js)向兼容MCP的客户端（如Claude Desktop或Postman Desktop应用程序）公开您的自动化API工具。我们建议您先使用Postman测试服务器，然后再使用LLM。

步骤1：从下载最新的Postman桌面应用程序 .

步骤2：阅读文档文章这里并了解如何在Postman应用程序中创建MCP请求。

步骤3：将MCP请求的类型设置为 STDIO 并将命令设置为 node .

对于Windows用户，您可以通过运行以下命令获得节点的完整路径：

Get-Command node | Select-Object -ExpandProperty Source

适用于macOS/Linux用户，您可以通过运行以下命令获得节点的完整路径：

which node

要检查任何平台上的节点版本，请运行：

node --version

对于Windows用户，获取到的绝对路径 mcpServer.js，运行：

Get-Location | Select-Object -ExpandProperty Path

然后追加 \mcpServer.js 到路径。

适用于macOS/Linux用户，获取到的绝对路径 mcpServer.js，运行：

realpath mcpServer.js

使用node命令后跟完整路径 mcpServer.js 作为新Postman MCP请求的命令。然后单击连接按钮。您应该看到在生成服务器之前选择的工具列表。在将MCP服务器连接到LLM之前，您可以在这里测试每个工具是否正常工作。

🔗 MCP客户端配置

您可以将MCP服务器连接到各种MCP客户端。下面是Claude Desktop和VS Code的详细说明。

📋 获取所需路径

在配置任何MCP客户端之前，您需要Node.js的绝对路径和您的 mcpServer.js 文件。

🪟 windows用户

获取Node.js路径：

Get-Command node | Select-Object -ExpandProperty Source

输出示例： C:\nvm4w\nodejs\node.exe

如果第一种方法不起作用，则采用替代方法：

where.exe node

获取当前目录路径：

Get-Location | Select-Object -ExpandProperty Path

输出示例： C:\Users\mohal\Downloads\google-appscriot-mcp-server

完整的mcpServer.js路径：

Join-Path (Get-Location) "mcpServer.js"

输出示例： C:\Users\mohal\Downloads\google-appscriot-mcp-server\mcpServer.js

快速复制粘贴命令以获取两个路径：

Write-Host "Node.js path: $((Get-Command node).Source)"
Write-Host "mcpServer.js path: $(Join-Path (Get-Location) 'mcpServer.js')"

🍎 macOS用户

获取Node.js路径：

which node

输出示例： /usr/local/bin/node 或 /opt/homebrew/bin/node

获取mcpServer.js路径：

realpath mcpServer.js

输出示例： /Users/username/google-apps-script-mcp-server/mcpServer.js

替代方法：

echo "$(pwd)/mcpServer.js"

快速复制粘贴命令以获取两个路径：

echo "Node.js path: $(which node)"
echo "mcpServer.js path: $(realpath mcpServer.js)"

🐧 Linux用户

获取Node.js路径：

which node

输出示例： /usr/bin/node 或 /usr/local/bin/node

获取mcpServer.js路径：

realpath mcpServer.js

输出示例： /home/username/google-apps-script-mcp-server/mcpServer.js

快速复制粘贴命令以获取两个路径：

echo "Node.js path: $(which node)"
echo "mcpServer.js path: $(realpath mcpServer.js)"

✅ 验证Node.js版本

在任何平台上，验证您的Node.js版本：

node --version

确保它显示 v18.0.0 或更高。

🤖 Claude桌面设置

步骤1：请注意上一节中的完整路径。

步骤2：打开克劳德桌面并导航到：

设置 → 开发者 → 编辑配置

步骤3：添加您的MCP服务器配置：

配置模板

{
  "mcpServers": {
    "google-apps-script": {
      "command": "",
      "args": [""],
      "env": {
        "GOOGLE_APP_SCRIPT_API_CLIENT_ID": "your_client_id_here",
        "GOOGLE_APP_SCRIPT_API_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

Windows示例

{
  "mcpServers": {
    "google-apps-script": {
      "command": "C:\\nvm4w\\nodejs\\node.exe",
      "args": ["C:\\Users\\mohal\\Downloads\\google-appscriot-mcp-server\\mcpServer.js"],
      "env": {
        "GOOGLE_APP_SCRIPT_API_CLIENT_ID": "1234567890-abcdefghijk.apps.googleusercontent.com",
        "GOOGLE_APP_SCRIPT_API_CLIENT_SECRET": "GOCSPX-abcdefghijklmnopqrstuvwxyz"
      }
    }
  }
}

macOS/Linux示例

{
  "mcpServers": {
    "google-apps-script": {
      "command": "/usr/local/bin/node",
      "args": ["/Users/username/google-apps-script-mcp-server/mcpServer.js"],
      "env": {
        "GOOGLE_APP_SCRIPT_API_CLIENT_ID": "1234567890-abcdefghijk.apps.googleusercontent.com",
        "GOOGLE_APP_SCRIPT_API_CLIENT_SECRET": "GOCSPX-abcdefghijklmnopqrstuvwxyz"
      }
    }
  }
}

步骤4：用您的实际值替换OAuth凭据 .env 文件。

步骤5：保存配置并重新启动Claude Desktop。

步骤6：通过在Claude Desktop中检查MCP服务器旁边是否显示绿色圆圈指示器来验证连接。

📝 VS代码设置（Cline/MCP扩展）

VS Code可以通过以下扩展使用MCP服务器 克莱恩 或其他MCP兼容扩展。

与Cline扩展一起使用

步骤1：安装临床扩展来自VS Code市场。

步骤2：打开VS代码设置(Ctrl+, 在Windows/Linux操作系统上， Cmd+, 在macOS上）。

步骤3：在设置中搜索“Cline”或“MCP”。

步骤4：添加您的MCP服务器配置：

方法1:VS代码设置.json

添加到您的VS代码 settings.json （可通过以下方式访问 Ctrl+Shift+P → “首选项：打开设置（JSON）”）：

{
  "cline.mcpServers": {
    "google-apps-script": {
      "command": "C:\\nvm4w\\nodejs\\node.exe",
      "args": ["C:\\Users\\mohal\\Downloads\\google-appscriot-mcp-server\\mcpServer.js"],
      "env": {
        "GOOGLE_APP_SCRIPT_API_CLIENT_ID": "your_client_id_here",
        "GOOGLE_APP_SCRIPT_API_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

方法2：工作空间配置

创建一个 .vscode/settings.json 项目根目录中的文件：

{
  "cline.mcpServers": {
    "google-apps-script": {
      "command": "node",
      "args": ["./mcpServer.js"],
      "env": {
        "GOOGLE_APP_SCRIPT_API_CLIENT_ID": "your_client_id_here",
        "GOOGLE_APP_SCRIPT_API_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

🔧 配置文件位置

Claude桌面配置位置：

视窗: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/claude-desktop/claude_desktop_config.json

VS代码设置位置：

视窗: %APPDATA%\Code\User\settings.json
macOS: ~/Library/Application Support/Code/User/settings.json
Linux: ~/.config/Code/User/settings.json

🔑 记住：

替换 your_actual_client_id 和 your_actual_client_secret 使用您的OAuth凭据
根据上述命令的实际系统输出更新路径
使用您的实际用户名，而不是 username 在小径上
确保你已经跑过了 npm run setup-oauth 在配置MCP客户端之前

🔍 故障排除

常见问题及解决方法

1.“未找到命令”或“未找到节点”错误

问题：MCP客户端找不到Node.js可执行文件 解决方案:

确保Node.js已正确安装并位于PATH中
使用Node.js可执行文件的绝对路径（推荐）
使用验证Node.js版本是否为18+ node --version
在Windows上，检查是否安装了多个Node.js版本

2.“未定义读取”错误

问题：您的Node.js版本低于18 解决方案:

推荐：升级到Node.js 18+
替代：安装 node-fetch 作为依赖关系：

  npm install node-fetch

然后修改每个工具文件以导入fetch：

  import fetch from 'node-fetch';

3.OAuth身份验证错误

问题：身份验证失败或令牌问题 解决方案:

验证您的OAuth凭据是否正确 .env 文件
确保在MCP配置中正确设置环境变量
重新运行OAuth安装程序： npm run setup-oauth
检查您是否遵循了Google Cloud Console设置中的所有步骤
验证回调URL是否准确： http://localhost:3001/oauth/callback
确保您的Google帐户已添加为测试用户

4.“授权错误：访问被阻止”

问题：Google OAuth同意屏幕配置问题 解决方案:

确保您的应用程序已为“外部”用户配置
在OAuth同意屏幕中添加您的Gmail地址作为测试用户
验证是否添加了所有必需的范围
确保OAuth同意屏幕已正确发布

5.MCP服务器未出现在Claude Desktop中

问题：配置文件语法或路径问题 解决方案:

检查配置文件语法（有效的JSON）
确保文件路径使用正确的转义（Windows上的双反斜杠）
配置更改后重新启动Claude Desktop
检查Claude Desktop日志中的错误消息
验证配置文件是否在正确的位置

6.VS代码/临床连接问题

问题：扩展程序无法识别MCP服务器 解决方案:

验证扩展是否已正确安装和启用
检查MCP配置是否在正确的设置位置
配置更改后重新加载VS Code窗口
如果全局设置不起作用，请使用特定于工作区的设置

7.“权限被拒绝”错误（macOS/Linux）

问题：文件权限问题 解决方案:

制作 mcpServer.js 可执行文件： chmod +x mcpServer.js
或者使用完整节点命令： node /path/to/mcpServer.js
检查文件所有权和权限

8.“EADDRINUSE”或港口冲突

问题：在OAuth设置期间，端口3001已在使用中 解决方案:

终止使用端口3001的所有进程：

  # Find process using port 3001
  lsof -i :3001  # macOS/Linux
  netstat -ano | findstr :3001  # Windows

  # Kill the process
  kill -9 
  # macOS/Linux
  taskkill /PID 
 /F  # Windows

或临时更改端口 oauth-setup.js

9.“令牌过期”或“凭据无效”错误

问题：OAuth令牌已过期或无效 解决方案:

重新运行OAuth安装程序： npm run setup-oauth
清除存储的令牌并重新进行身份验证
检查您的OAuth应用程序凭据是否未更改
验证OAuth应用程序在谷歌云控制台中是否仍处于活动状态

10.脚本执行权限错误

问题：无法执行脚本或访问项目 解决方案:

确保您的Google帐户可以访问Apps Script项目
验证脚本是否与您的帐户共享
检查是否授予了所需的范围
对于脚本执行，确保脚本已部署并可执行

11.部署的web应用程序上的“拒绝访问”或“您需要访问”

问题：使用Google服务的脚本(DriveApp, SpreadsheetApp等等）在部署的URL工作之前需要手动授权。 解决方案：参见脚本授权有关分步说明的部分。

测试您的配置

独立测试MCP服务器

npm start

如果它启动时没有错误，则您的基本设置是正确的。

测试OAuth身份验证

npm run test-oauth

这将验证您的OAuth设置是否正常工作。

使用调试日志记录进行测试

npm run debug

这提供了详细的日志记录，以帮助识别问题。

测试单个工具

npm run list-tools

这列出了所有可用的工具及其参数。

日志文件和调试

启用调试日志记录

设置 LOG_LEVEL 环境变量：

# In .env file
LOG_LEVEL=debug

# Or run with debug
npm run debug

检查OAuth流

OAuth设置过程提供详细的输出。注意：

浏览器打开成功
授权码捕获
代币兑换成功
测试API调用成功

常见日志消息

成功消息:

OAuth tokens loaded successfully
Server ready to handle MCP requests
Tool executed successfully

警告信息:

Token refresh required （正常运行）
Retrying API call with refreshed token

错误消息:

OAuth credentials not found → 检查.env文件
Failed to refresh token → 重新运行OAuth安装程序
API call failed → 检查权限和配额

获取帮助

支持资源

Google应用程序脚本API文档: https://developers.google.com/apps-script/api
MCP协议文件: https://modelcontextprotocol.io/
OAuth 2.0指南: https://developers.google.com/identity/protocols/oauth2

要收集的诊断信息

寻求帮助时，请提供：

Node.js版本(node --version)
操作系统和版本
来自控制台/日志的错误消息
错误发生前遵循的步骤
您的内容 .env 文件（无秘密）
MCP客户端配置（无秘密）

🚀 高级用法

环境变量

核心配置

# Required OAuth credentials
GOOGLE_APP_SCRIPT_API_CLIENT_ID=your_client_id
GOOGLE_APP_SCRIPT_API_CLIENT_SECRET=your_client_secret

# Optional configuration
LOG_LEVEL=info                    # debug, info, warn, error
NODE_ENV=development              # development, production
PORT=3001                        # OAuth callback port

日志记录级别

debug：详细的调试信息
info：一般信息信息
warn：警告信息
error：仅显示错误消息

在生产中运行

使用PM2流程管理器

# Install PM2
npm install -g pm2

# Start with PM2
pm2 start mcpServer.js --name "gas-mcp-server"

# Monitor
pm2 status
pm2 logs gas-mcp-server

# Auto-restart on system boot
pm2 startup
pm2 save

使用Docker

构建Docker镜像：

docker build -t google-apps-script-mcp .

使用Docker运行：

docker run -i --rm --env-file=.env google-apps-script-mcp

Docker编写设置：

version: '3.8'
services:
  gas-mcp:
    build: .
    env_file:
      - .env
    stdin_open: true
    tty: true

Claude桌面与Docker

{
  "mcpServers": {
    "google-apps-script": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file=.env", "google-apps-script-mcp"]
    }
  }
}

定制工具开发

添加新工具

创建新的工具文件 在 tools/google-app-script-api/apps-script-api/:

import { getAuthHeaders } from '../../../lib/oauth-helper.js';

const executeFunction = async ({ param1, param2 }) => {
  const baseUrl = 'https://script.googleapis.com';
  
  try {
    const headers = await getAuthHeaders();
    const response = await fetch(`${baseUrl}/v1/your-endpoint`, {
      method: 'POST',
      headers,
      body: JSON.stringify({ param1, param2 })
    });
    
    return await response.json();
  } catch (error) {
    throw new Error(`API call failed: ${error.message}`);
  }
};

export { executeFunction };

添加到paths.js:

export const toolPaths = [
  // ...existing paths...
  'google-app-script-api/apps-script-api/your-new-tool.js'
];

更新工具说明 在MCP服务器工具定义中。

工具模板结构

import { getAuthHeaders } from '../../../lib/oauth-helper.js';

/**
 * Tool description and JSDoc comments
 */
const executeFunction = async (args) => {
  const baseUrl = 'https://script.googleapis.com';
  
  try {
    // 1. Validate parameters
    if (!args.requiredParam) {
      throw new Error('requiredParam is required');
    }
    
    // 2. Get authentication headers
    const headers = await getAuthHeaders();
    
    // 3. Make API call
    const response = await fetch(`${baseUrl}/v1/endpoint`, {
      method: 'GET/POST/PUT/DELETE',
      headers,
      body: JSON.stringify(args) // for POST/PUT
    });
    
    // 4. Handle response
    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }
    
    return await response.json();
    
  } catch (error) {
    console.error('Tool execution failed:', error);
    throw error;
  }
};

export { executeFunction };

服务器发送事件（SSE）模式

对于与web界面的实时通信：

npm run start-sse

服务器将在HTTP上运行，并支持SSE流式响应。

多种环境支持

开发环境

NODE_ENV=development
LOG_LEVEL=debug
GOOGLE_APP_SCRIPT_API_CLIENT_ID=dev_client_id
GOOGLE_APP_SCRIPT_API_CLIENT_SECRET=dev_client_secret

生产环境

NODE_ENV=production
LOG_LEVEL=info
GOOGLE_APP_SCRIPT_API_CLIENT_ID=prod_client_id
GOOGLE_APP_SCRIPT_API_CLIENT_SECRET=prod_client_secret

性能优化

令牌缓存

OAuth助手会自动将访问令牌缓存在内存中，并根据需要刷新它们。

请求批处理

对于多个操作，在可能的情况下考虑批处理请求：

// Instead of multiple individual calls
const results = await Promise.all([
  tool1(args1),
  tool2(args2),
  tool3(args3)
]);

速率限制

Google应用程序脚本API有速率限制。这些工具包括具有指数回退的自动重试逻辑。

安全最佳实践

凭据管理

永不承诺 .env 文件到版本控制
使用不同的OAuth应用程序进行开发和生产
定期轮换OAuth凭据
在谷歌云控制台中监控OAuth应用程序的使用情况

访问控制

使用最低权限OAuth作用域
仅将必要的测试用户添加到OAuth应用程序
监控脚本执行日志以防止未经授权的访问
为所有API调用实现日志记录

网络安全

在安全环境中运行MCP服务器
使用HTTPS进行生产部署
实施适当的防火墙规则
监控网络流量是否异常

🛠️ 其他CLI命令

可用的npm脚本

# Start the MCP server
npm start

# Start with SSE support
npm run start-sse

# Start with debug logging
npm run debug

# Start SSE with debug logging
npm run debug-sse

# List all available tools and their descriptions
npm run list-tools

# Test OAuth authentication
npm run test-oauth

# Set up or refresh OAuth tokens
npm run setup-oauth

# Test logging functionality
npm run test-logging

工具信息

列出可用工具

npm run list-tools

输出示例：

Available Tools:

Google Apps Script API:
  script-projects-create
    Description: Create a new Google Apps Script project
    Parameters:
      - title (required): The title of the new script project
      - parentId (optional): The ID of the parent project

  script-projects-get
    Description: Get metadata of a Google Apps Script project
    Parameters:
      - scriptId (required): The ID of the script project to retrieve
      - fields (optional): Specific fields to include in response
      [... additional parameters ...]

从Postman添加新工具

访问邮递员MCP生成器
为Google应用程序脚本或其他API选择新的API请求
生成新的MCP服务器
将新工具文件复制到现有工具文件中 tools/ 文件夹
更新 tools/paths.js 包括新的工具参考
重新启动MCP服务器

💬 支持和社区

获取帮助

GitHub问题：报告错误和请求功能
邮递员不和谐：加入 #mcp-lab 频道在邮递员不和谐
文档：参观邮递员MCP生成器获取更新

贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支
添加新功能的测试
提交拉取请求

许可证

该项目根据MIT许可证获得许可。有关详细信息，请参阅LICENSE文件。

Google Apps Script MCP Server

快速接入

详细介绍

谷歌应用程序脚本MCP服务器

📋 目录

🌟 概述

🎥 演示视频

🚀 特性

核心能力

安全功能

⚙️ 先决条件

🚀 快速入门指南

1.克隆存储库

2.安装依赖项

3.设置谷歌云OAuth

4.运行OAuth安装程序

5.测试服务器

1.1 Node.js的MCP配置

1.2 Docker的MCP配置

📖 详细的设置说明

步骤1:谷歌云控制台设置

1.1创建或选择谷歌云项目

1.2启用所需的API

1.3配置OAuth同意屏幕

1.4创建OAuth 2.0凭据

步骤2：配置环境变量

2.1创建.env文件

2.2添加OAuth凭据

步骤3:OAuth身份验证设置

3.1运行OAuth安装程序

3.2授予权限

3.3验证令牌存储

步骤4：测试您的设置

4.1测试MCP服务器

4.2使用可用命令进行测试

🛠️ 可用工具

项目管理工具

1. script-projects-create

2. script-projects-get

3. script-projects-get-content

4. script-projects-update-content

版本管理工具

5. script-projects-versions-create

6. script-projects-versions-get

7. script-projects-versions-list

部署管理工具

8. script-projects-deployments-create

9. script-projects-deployments-get

10. script-projects-deployments-list

11. script-projects-deployments-update

12. script-projects-deployments-delete

执行和监控工具

13. script-scripts-run

14. script-processes-list

15. script-processes-list-script-processes

16. script-projects-get-metrics

工具类别摘要

常见用例

⚠️ 脚本授权

🌐 使用Postman测试MCP服务器

🔗 MCP客户端配置

📋 获取所需路径

🪟 windows用户

🍎 macOS用户

🐧 Linux用户

✅ 验证Node.js版本

🤖 Claude桌面设置

配置模板

Windows示例

macOS/Linux示例

📝 VS代码设置（Cline/MCP扩展）

与Cline扩展一起使用

方法1:VS代码设置.json

方法2：工作空间配置

🔧 配置文件位置

Claude桌面配置位置：

VS代码设置位置：

🔍 故障排除

常见问题及解决方法

1.“未找到命令”或“未找到节点”错误

1. `script-projects-create`

2. `script-projects-get`

3. `script-projects-get-content`

4. `script-projects-update-content`

5. `script-projects-versions-create`

6. `script-projects-versions-get`

7. `script-projects-versions-list`

8. `script-projects-deployments-create`

9. `script-projects-deployments-get`

10. `script-projects-deployments-list`

11. `script-projects-deployments-update`

12. `script-projects-deployments-delete`

13. `script-scripts-run`

14. `script-processes-list`

15. `script-processes-list-script-processes`

16. `script-projects-get-metrics`