Google Apps Script MCP Server

Google Apps Script MCP 服务

作者：mohalmah
许可证：MIT License
仓库：google-apps-script-mcp-server

欢迎使用 Google Apps Script MCP（Model Context Protocol）服务！🚀

此 MCP 服务可与 Google Apps Script API 全面集成，让你通过任何兼容 MCP 的客户端（例如 Claude Desktop、搭配 Cline 的 VS Code 或 Postman）管理脚本项目、部署、版本和执行。

📋 目录

• 概述
• 功能
• 前提条件
• 快速入门指南
• 详细设置说明
• 可用工具
• 脚本授权
• MCP 客户端配置
• 故障排除
• 高级用法

🌟 概述

此 MCP 服务可实现与 Google Apps Script 的无缝交互，功能包括：

• ✅ OAuth 2.0 身份验证 - 安全管理令牌并自动刷新
• ✅ 16 种全面的工具 - 完整覆盖 Google Apps Script API
• ✅ 符合 MCP 协议 - 支持 Claude Desktop、VS Code 和其他 MCP 客户端
• ✅ 安全的令牌存储 - 针对不同操作系统安全存储刷新令牌
• ✅ 自动刷新令牌 - 自动处理令牌过期
• ✅ 详细日志记录 - 全面的错误处理和调试功能

🎥 演示视频

观看 Google Apps Script MCP 服务的实际操作：通过 VS Code AI Agent 创建项目、管理部署并执行脚本。

🚀 功能

核心功能

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

安全功能

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

⚙️ 前提条件

开始之前，请确保你具备：

• Node.js（需要 v18+，推荐 v20+）- 在此下载
• npm（随 Node.js 一同安装）
• Google 账号，且可访问 Google Cloud Console
• Git（用于克隆仓库）

🚀 快速入门指南

1. 克隆仓库

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

2. 安装依赖项

npm install

3. 设置 Google Cloud OAuth

请参阅下方的详细 OAuth 设置指南。

4. 运行 OAuth 设置

npm run setup-oauth

5. 测试服务

npm start

1.1 Node.js 的 MCP 配置

编辑你的 claude_desktop_config.json 文件：

• Windows：%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 步：Google Cloud Console 设置

1.1 创建或选择 Google Cloud 项目

1. 前往 Google Cloud Console
2. 点击顶部的项目下拉菜单
3. 点击 "New Project" 或选择现有项目
4. 如果要创建新项目：
   • 输入项目名称（例如，“Google Apps Script MCP”）
   • 记下项目 ID（稍后会用到）
   • 点击 "Create"

1.2 启用所需 API

1. 在 Google Cloud Console 中，前往 APIs & Services → Library
2. 搜索并启用以下 API：
   • Google Apps Script API（必需）
   • Google Drive API（建议启用，以便访问文件）
   • Google Cloud Resource Manager API（用于项目操作）

对于 Google Apps Script API：

1. 搜索 "Google Apps Script API"
2. 点击搜索结果
3. 点击 "Enable"
4. 等待 API 启用（可能需要几分钟）

1.3 配置 OAuth 同意屏幕

1. 前往 APIs & Services → OAuth consent screen
2. 选择 External（除非你属于 Google Workspace 组织）
3. 填写所需信息：
   • App name："Google Apps Script MCP Server"
   • User support email：你的电子邮件地址
   • App logo：（可选）
   • App domain：开发期间留空
   • Developer contact information：你的电子邮件地址
4. 点击 "Save and Continue"

配置范围（可选但建议配置）：

1. 点击 "Add or Remove Scopes"
2. 添加以下范围：
   • 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
3. 点击 "Update"

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

1. 点击 "Add Users"
2. 将你的 Gmail 地址添加为测试用户
3. 点击 "Save and Continue"

1.4 创建 OAuth 2.0 凭据

1. 前往 APIs & Services → Credentials
2. 点击 "+ CREATE CREDENTIALS" → "OAuth 2.0 Client IDs"
3. 在 Application Type 中，选择 "Web application"
4. 配置客户端：
   • Name："Google Apps Script MCP Client"
   • Authorized JavaScript origins：（暂时留空）
   • Authorized redirect URIs：准确添加以下 URL：

     http://localhost:3001/oauth/callback
     

5. 点击 "Create"
6. 重要：立即复制你的 Client ID 和 Client Secret
   • Client ID 格式示例：1234567890-abcdefghijklmnop.apps.googleusercontent.com
   • Client Secret 格式示例：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 替换为你的 Client ID
• 将 your_client_secret_here 替换为你的 Client Secret

第 3 步：OAuth 身份验证设置

3.1 运行 OAuth 设置

执行 OAuth 设置脚本：

npm run setup-oauth

此操作将：

1. 在 http://localhost:3001 启动临时本地服务
2. 打开默认浏览器并转到 Google 授权页面
3. 提示你向应用授予权限
4. 通过回调 URL 获取授权码
5. 使用授权码换取访问令牌和刷新令牌
6. 将刷新令牌安全地存储在操作系统凭据存储区中
7. 通过发起测试 API 调用来测试令牌

3.2 授予权限

浏览器打开后：

1. 选择你的 Google 账号（必须是你添加的测试用户）
2. 查看请求的权限：
   • 查看和管理你的 Google Apps Script 项目
   • 查看脚本执行情况和指标
   • 访问脚本部署
3. 点击“继续”或“允许”
4. 你应该会看到：“OAuth setup completed successfully！”

3.3 验证令牌存储

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

• Windows：Windows Credential Manager
• macOS：Keychain Access
• Linux：Secret Service API（GNOME Keyring/KDE Wallet）

第 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 服务提供 16 个全面的工具，用于管理 Google Apps Script：

项目管理工具

1. script-projects-create

用途：创建新的 Google Apps Script 项目 参数：

• 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 等 Google 服务，则必须先在 Apps Script 编辑器中手动授权脚本，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 Script 函数 参数：

• 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（必需）：要获取的具体指标字段

提供的内容：

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

工具类别摘要

类别	工具	用途
项目管理	create、get、get-content、update-content	管理脚本项目和源代码
版本控制	versions-create、versions-get、versions-list	管理脚本版本
部署	deployments-create、deployments-get、deployments-list、deployments-update、deployments-delete	管理脚本部署
执行	scripts-run	执行脚本函数
监控	processes-list、get-metrics	监控执行情况和性能

常见用例

开发工作流：

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

监控与调试：

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

生产环境管理：

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

⚠️ 脚本授权

当脚本使用 DriveApp、SpreadsheetApp、GmailApp 或 CalendarApp 等 Google 服务时，必须先手动授权，已部署的 Web 应用才能正常响应。MCP 服务的 API 部署不会触发 Google OAuth 同意流程。

如果已部署的 Web 应用返回“Access Denied”或“You need access”，请在部署后按以下步骤操作一次：

1. 在 Apps Script 编辑器中打开脚本：

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

   （将 {SCRIPT_ID} 替换为 script-projects-create 或 script-projects-get 返回的 ID。）

2. 点击任意调用 Google 服务的函数上的 Run（例如 doGet）。

3. 出现提示时，点击 Review Permissions。

4. 完成 Google OAuth 同意流程：

   • 选择你的 Google 账号
   • 点击 Advanced → Go to {project name} (unsafe)
   • 点击 Allow

5. 现在，已部署的 Web 应用就能正常运行了。

**注意：**这是 Google Apps Script 平台的要求，无法通过 API 绕过。

🌐 使用 Postman 测试 MCP 服务

MCP 服务（mcpServer.js）向 MCP 兼容客户端（例如 Claude Desktop 或 Postman Desktop Application）公开自动化 API 工具。我们建议先使用 Postman 测试服务，然后再使用大模型。

步骤 1：从 https://www.postman.com/downloads/ 下载最新的 Postman Desktop Application。

步骤 2：阅读此处的文档文章，了解如何在 Postman 应用中创建 MCP 请求。

步骤 3：将 MCP 请求类型设为 STDIO，并将命令设为 node <absolute/path/to/mcpServer.js>。

Windows 用户可以运行以下命令获取 node 的完整路径：

Get-Command node | Select-Object -ExpandProperty Source

macOS/Linux 用户可以运行以下命令获取 node 的完整路径：

which node

要在任何平台上检查 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 Request 的命令。然后点击 Connect 按钮。你应该会看到生成服务前所选工具的列表。在将 MCP 服务连接到大模型之前，可以在此测试每个工具是否正常运行。

🔗 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 Desktop 设置

第 1 步：记下上一节中的完整路径。

第 2 步：打开 Claude Desktop 并导航至：

• 设置 → 开发者 → 编辑配置

第 3 步：添加 MCP 服务配置：

配置模板

{
  "mcpServers": {
    "google-apps-script": {
      "command": "<absolute_path_to_node_executable>",
      "args": ["<absolute_path_to_mcpServer.js>"],
      "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 步：检查 MCP 服务旁边是否显示绿色圆点，确认连接正常。

📝 VS Code 设置（Cline/MCP 扩展）

VS Code 可通过 Cline 等扩展或其他兼容 MCP 的扩展使用 MCP 服务。

使用 Cline 扩展

第 1 步：从 VS Code 市场安装 Cline 扩展。

第 2 步：打开 VS Code 设置（Windows/Linux 上按 Ctrl+,，macOS 上按 Cmd+,）。

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

第 4 步：添加 MCP 服务配置：

方法 1：VS Code Settings.json

将配置添加到 VS Code 的 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 Desktop 配置位置：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Linux：~/.config/claude-desktop/claude_desktop_config.json

VS Code 设置位置：

• Windows：%APPDATA%\Code\User\settings.json
• macOS：~/Library/Application Support/Code/User/settings.json
• Linux：~/.config/Code/User/settings.json

🔑 请记住：

1. 将 your_actual_client_id 和 your_actual_client_secret 替换为你的 OAuth 凭据
2. 根据上述命令的实际输出更新路径
3. 在路径中使用你的实际用户名，而不是 username
4. 配置 MCP 客户端前，请确保已运行 npm run setup-oauth

🔍 故障排除

常见问题和解决方案

1. “找不到命令”或“找不到 Node”错误

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

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

2. “未定义 fetch”错误

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

• 推荐：升级到 Node.js 18+
• 替代方案：安装 node-fetch 作为依赖项：

  npm install node-fetch
  

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

  import fetch from 'node-fetch';
  

3. OAuth 身份验证错误

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

• 确认 .env 文件中的 OAuth 凭据正确
• 确保在 MCP 配置中正确设置了环境变量
• 重新运行 OAuth 设置：npm run setup-oauth
• 确认已完成 Google Cloud Console 设置中的所有步骤
• 确认回调 URL 完全一致：http://localhost:3001/oauth/callback
• 确保已将你的 Google 账号添加为测试用户

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

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

• 确保应用配置为面向“外部”用户
• 在 OAuth 同意屏幕中将你的 Gmail 地址添加为测试用户
• 确认已添加所有必需的范围
• 确保已正确发布 OAuth 同意屏幕

5. Claude Desktop 中未显示 MCP 服务

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

• 检查配置文件语法（有效的 JSON）
• 确保文件路径使用正确的转义方式（Windows 上使用双反斜杠）
• 更改配置后重启 Claude Desktop
• 检查 Claude Desktop 日志中的错误消息
• 确认配置文件位于正确的位置

6. VS Code/Cline 连接问题

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

• 确认扩展已正确安装并启用
• 检查 MCP 配置是否位于正确的设置位置
• 更改配置后重新加载 VS Code 窗口
• 如果全局设置不起作用，请使用工作区专属设置

7. “Permission denied”错误（macOS/Linux）

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

• 将 mcpServer.js 文件设为可执行：chmod +x mcpServer.js
• 或使用完整的 node 命令：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 <PID>  # macOS/Linux
  taskkill /PID <PID> /F  # Windows
  

• 或暂时更改 oauth-setup.js 中的端口

9. “Token expired”或“Invalid credentials”错误

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

• 重新运行 OAuth 设置：npm run setup-oauth
• 清除已存储的令牌并重新进行身份验证
• 检查 OAuth 应用凭据是否已更改
• 确认 OAuth 应用在 Google Cloud Console 中仍处于启用状态

10. 脚本执行权限错误

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

• 确保你的 Google 账号有权访问 Apps Script 项目
• 确认脚本已与您的账号共享
• 检查是否已授予所需的范围
• 执行脚本时，确保脚本已部署且可执行

11. 已部署的 Web 应用出现“Access Denied”或“You need access”

问题：使用 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 → 检查权限和配额

获取帮助

支持资源

1. Google Apps Script API 文档：https://developers.google.com/apps-script/api
2. MCP 协议文档：https://modelcontextprotocol.io/
3. 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 Compose 配置：

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

使用 Docker 配置 Claude Desktop

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

自定义工具开发

添加新工具

1. 在 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 };

2. 添加到 paths.js：

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

3. 在 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 Apps Script API 存在速率限制。这些工具包含自动重试逻辑，并采用指数退避策略。

安全最佳实践

凭据管理

• 切勿将 .env 文件提交到版本控制系统
• 开发环境和生产环境使用不同的 OAuth 应用
• 定期轮换 OAuth 凭据
• 在 Google Cloud Console 中监控 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 添加新工具

1. 访问 Postman MCP 生成器
2. 为 Google Apps Script 或其他 API 选择新的 API 请求
3. 生成新的 MCP 服务
4. 将新的工具文件复制到现有的 tools/ 文件夹
5. 更新 tools/paths.js，添加新的工具引用
6. 重启 MCP 服务

💬 支持与社区

获取帮助

• GitHub Issues：报告错误并请求新功能
• Postman Discord：加入 Postman Discord 中的 #mcp-lab 频道
• 文档：访问 Postman MCP 生成器 获取更新

贡献

欢迎贡献！请：

1. Fork 此仓库
2. 创建功能分支
3. 为新功能添加测试
4. 提交拉取请求

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。