Google Appscript MCP Server

🚀 Google Apps Script MCP Server

Google Apps Script MCP（模型上下文协议）服务器是一个强大的工具，它允许你通过任何兼容MCP的客户端，如Claude Desktop、带有Cline的VS Code或Postman，来管理Google Apps Script项目、部署、版本和执行。

🚀 快速开始

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

✨ 主要特性

核心功能

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

安全特性

• OAuth 2.0认证：安全的令牌管理，支持自动刷新。
• 安全令牌存储：使用特定于操作系统的安全存储来保存刷新令牌。
• 自动令牌刷新：自动处理令牌过期问题。
• 详细日志记录：全面的错误处理和调试功能。

📦 安装指南

步骤1：克隆并安装

克隆仓库：

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

安装依赖：

npm install

步骤2：Google Cloud控制台设置

2.1 创建或选择Google Cloud项目

1. 访问Google Cloud控制台。
2. 点击顶部的项目下拉菜单。
3. 点击“新建项目”或选择现有项目。
4. 如果创建新项目：
   • 输入项目名称（例如：“Google Apps Script MCP”）。
   • 记录你的项目ID（后续会用到）。
   • 点击“创建”。

2.2 启用所需的API

1. 在Google Cloud控制台中，导航到“API和服务”→“库”。
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. 点击“启用”。
4. 等待API启用（可能需要几分钟）。

2.3 配置OAuth同意屏幕

1. 转到“API和服务”→“OAuth同意屏幕”。
2. 选择“外部”（除非你在Google Workspace组织中）。
3. 填写所需信息：
   • 应用名称：“Google Apps Script MCP Server”
   • 用户支持电子邮件：你的电子邮件地址
   • 应用徽标：（可选）
   • 应用域名：开发阶段留空
   • 开发者联系信息：你的电子邮件地址
4. 点击“保存并继续”。

配置范围（可选但推荐）：

1. 点击“添加或删除范围”。
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. 点击“更新”。

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

1. 点击“添加用户”。
2. 添加你的Gmail地址作为测试用户。
3. 点击“保存并继续”。

2.4 创建OAuth 2.0凭证

1. 转到“API和服务”→“凭证”。
2. 点击“+ 创建凭证”→“OAuth 2.0客户端ID”。
3. 对于应用类型，选择“Web应用程序”。
4. 配置客户端：
   • 名称：“Google Apps Script MCP Client”
   • 授权的JavaScript来源：（暂时留空）
   • 授权的重定向URI：添加以下URL：

     http://localhost:3001/oauth/callback
     

5. 点击“创建”。
6. 重要：立即复制你的客户端ID和客户端密钥。
   • 客户端ID格式类似：1234567890-abcdefghijklmnop.apps.googleusercontent.com
   • 客户端密钥格式类似：GOCSPX-abcdefghijklmnopqrstuvwxyz

步骤3：配置环境变量

3.1 创建.env文件

在项目根目录下创建一个.env文件：

# 在Windows上
type nul > .env

# 在macOS/Linux上
touch .env

3.2 添加OAuth凭证

编辑.env文件并添加你的凭证：

# Google Apps Script API OAuth配置
GOOGLE_APP_SCRIPT_API_CLIENT_ID=your_client_id_here
GOOGLE_APP_SCRIPT_API_CLIENT_SECRET=your_client_secret_here

# 可选：日志级别
LOG_LEVEL=info

将占位符替换为实际值：

• 将your_client_id_here替换为你的客户端ID。
• 将your_client_secret_here替换为你的客户端密钥。

步骤4：OAuth认证设置

4.1 运行OAuth设置

执行OAuth设置脚本：

npm run setup-oauth

此操作的作用：

1. 在http://localhost:3001上启动一个临时本地服务器。
2. 打开默认浏览器，跳转到Google的授权页面。
3. 要求你授予应用程序权限。
4. 通过回调URL捕获授权码。
5. 将授权码交换为访问令牌和刷新令牌。
6. 将刷新令牌安全地存储在操作系统的凭证存储中。
7. 通过进行测试API调用来测试令牌。

4.2 授予权限

当浏览器打开时：

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

4.3 验证令牌存储

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

• Windows：Windows凭证管理器。
• macOS：钥匙串访问。
• Linux：秘密服务API（GNOME Keyring/KDE Wallet）。

步骤5：测试你的设置

5.1 测试MCP服务器

npm start

你应该看到类似以下的输出：

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

5.2 使用可用命令进行测试

# 列出所有可用工具
npm run list-tools

# 测试OAuth连接
npm run test-oauth

# 启用调试日志
npm run debug

💻 使用示例

基础用法

以下是使用script-projects-create工具创建新Google Apps Script项目的示例：

// 创建一个用于自动化任务的新脚本
{
  "title": "My Automation Script",
  "parentId": "1234567890"
}

高级用法

以下是使用script-scripts-run工具远程触发脚本执行的示例：

// 假设你有一个名为'myFunction'的函数，并且脚本ID为'1ABC123def456GHI789jkl'
{
  "scriptId": "1ABC123def456GHI789jkl",
  "functionName": "myFunction",
  "parameters": {
    "param1": "value1",
    "param2": "value2"
  }
}

📚 详细文档

可用工具

此MCP服务器提供16个全面的工具，用于管理Google Apps Script：

类别	工具	用途
项目管理	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触发自动化工作流。

测试MCP服务器与Postman

MCP服务器（mcpServer.js）将你的自动化API工具暴露给兼容MCP的客户端，如Claude Desktop或Postman桌面应用程序。我们建议你先使用Postman测试服务器，然后再将其与大型语言模型（LLM）一起使用。

步骤1：从https://www.postman.com/downloads/下载最新的Postman桌面应用程序。

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

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

对于Windows用户，可以通过以下命令获取Node.js的完整路径：

Get-Command node | Select-Object -ExpandProperty Source

对于macOS/Linux用户，可以通过以下命令获取Node.js的完整路径：

which node

要检查任何平台上的Node.js版本，请运行：

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

确保显示的版本为18或更高。

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：通过检查Claude Desktop中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

快速配置示例

将以下路径替换为你系统的实际路径：

当前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": "your_actual_client_id",
        "GOOGLE_APP_SCRIPT_API_CLIENT_SECRET": "your_actual_client_secret"
      }
    }
  }
}

macOS设置：

{
  "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": "your_actual_client_id",
        "GOOGLE_APP_SCRIPT_API_CLIENT_SECRET": "your_actual_client_secret"
      }
    }
  }
}

Linux设置：

{
  "mcpServers": {
    "google-apps-script": {
      "command": "/usr/bin/node",
      "args": ["/home/username/google-apps-script-mcp-server/mcpServer.js"],
      "env": {
        "GOOGLE_APP_SCRIPT_API_CLIENT_ID": "your_actual_client_id",
        "GOOGLE_APP_SCRIPT_API_CLIENT_SECRET": "your_actual_client_secret"
      }
    }
  }
}

🔑 请记住：

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

🔧 技术细节

环境变量

核心配置

# 必需的OAuth凭证
GOOGLE_APP_SCRIPT_API_CLIENT_ID=your_client_id
GOOGLE_APP_SCRIPT_API_CLIENT_SECRET=your_client_secret

# 可选配置
LOG_LEVEL=info                    # debug, info, warn, error
NODE_ENV=development              # development, production
PORT=3001                        # OAuth回调端口

日志级别

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

在生产环境中运行

使用PM2进程管理器

# 安装PM2
npm install -g pm2

# 使用PM2启动
pm2 start mcpServer.js --name "gas-mcp-server"

# 监控
pm2 status
pm2 logs gas-mcp-server

# 系统启动时自动重启
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 = [
  // ...现有路径...
  'google-app-script-api/apps-script-api/your-new-tool.js'
];

3. 在MCP服务器工具定义中更新工具描述。

工具模板结构

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

/**
 * 工具描述和JSDoc注释
 */
const executeFunction = async (args) => {
  const baseUrl = 'https://script.googleapis.com';
  
  try {
    // 1. 验证参数
    if (!args.requiredParam) {
      throw new Error('requiredParam is required');
    }
    
    // 2. 获取认证头
    const headers = await getAuthHeaders();
    
    // 3. 进行API调用
    const response = await fetch(`${baseUrl}/v1/endpoint`, {
      method: 'GET/POST/PUT/DELETE',
      headers,
      body: JSON.stringify(args) // 适用于POST/PUT
    });
    
    // 4. 处理响应
    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

服务器将以支持SSE的HTTP模式运行，用于流式响应。

多环境支持

开发环境

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助手会自动将访问令牌缓存在内存中，并在需要时刷新。

请求批处理

对于多个操作，尽可能考虑批处理请求：

// 代替多个单独的调用
const results = await Promise.all([
  tool1(args1),
  tool2(args2),
  tool3(args3)
]);

速率限制

Google Apps Script API有速率限制。工具中包含了带有指数退避的自动重试逻辑。

安全最佳实践

凭证管理

• 切勿将.env文件提交到版本控制中。
• 在开发和生产环境中使用不同的OAuth应用。
• 定期轮换OAuth凭证。
• 在Google Cloud控制台中监控OAuth应用的使用情况。

访问控制

• 使用最小权限的OAuth范围。
• 仅向OAuth应用添加必要的测试用户。
• 监控脚本执行日志，以防止未经授权的访问。
• 对所有API调用进行日志记录。

网络安全

• 在安全的环境中运行MCP服务器。
• 在生产部署中使用HTTPS。
• 实施适当的防火墙规则。
• 监控网络流量，以检测异常情况。

🔍 故障排除

常见问题及解决方案

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

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

• 确保Node.js已正确安装并添加到系统路径中。
• 使用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控制台设置的所有步骤进行操作。
• 验证回调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 Code/Cline连接问题

问题：扩展未识别MCP服务器。 解决方案：

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

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

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

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

8. “EADDRINUSE”或端口冲突

问题：OAuth设置期间端口3001已被使用。 解决方案：

• 杀死使用端口3001的任何进程：

  # 查找使用端口3001的进程
  lsof -i :3001  # macOS/Linux
  netstat -ano | findstr :3001  # Windows
  
  # 杀死进程
  kill -9 <PID>  # macOS/Linux
  taskkill /PID <PID> /F  # Windows
  

• 或者临时更改oauth-setup.js中的端口。

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

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

• 重新运行OAuth设置：npm run setup-oauth。
• 清除存储的令牌并重新进行身份验证。
• 检查你的OAuth应用凭证是否未更改。
• 验证OAuth应用在Google Cloud控制台中是否仍然处于活动状态。

10. 脚本执行权限错误

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

• 确保你的Google账户有权访问Apps Script项目。
• 验证脚本是否已与你的账户共享。
• 检查是否授予了所需的范围。
• 对于脚本执行，确保脚本已部署且可执行。

测试你的配置

独立测试MCP服务器

npm start

如果它能正常启动且没有错误，说明你的基本设置正确。

测试OAuth认证

npm run test-oauth

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

使用调试日志进行测试

npm run debug

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

测试单个工具

npm run list-tools

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

日志文件和调试

启用调试日志

设置LOG_LEVEL环境变量：

# 在.env文件中
LOG_LEVEL=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客户端配置（不包含机密信息）。

🛠️ 附加CLI命令

可用的npm脚本

# 启动MCP服务器
npm start

# 启动并支持SSE
npm run start-sse

# 启动并使用调试日志
npm run debug

# 启动SSE并使用调试日志
npm run debug-sse

# 列出所有可用工具及其描述
npm run list-tools

# 测试OAuth认证
npm run test-oauth

# 设置或刷新OAuth令牌
npm run setup-oauth

# 测试日志功能
npm run test-logging

工具信息

列出可用工具

npm run list-tools

示例输出：

可用工具：

Google Apps Script API:
  script-projects-create
    描述：创建一个新的Google Apps Script项目
    参数：
      - title（必需）：新脚本项目的标题
      - parentId（可选）：父项目的ID

  script-projects-get
    描述：获取Google Apps Script项目的元数据
    参数：
      - scriptId（必需）：要检索的脚本项目的ID
      - fields（可选）：要包含在响应中的特定字段
      [... 其他参数 ...]

从Postman添加新工具

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

💬 支持与社区

获取帮助

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

贡献

欢迎贡献代码！请按照以下步骤操作：

1. 克隆仓库。
2. 创建一个功能分支。
3. 为新功能添加测试。
4. 提交拉取请求。

📄 许可证

本项目采用MIT许可证。有关详细信息，请参阅LICENSE文件。