apps-script-mcp-server

一个MCP服务器，让Claude能够直接读取和推送Google Apps Script（.gs、.html、appsscript.json）代码到脚本项目中——无需再手动将代码复制粘贴到Apps Script编辑器中。

专为Kwara疾病监测系统（KWARAB仪表盘）构建，但适用于任何你有编辑权限的Apps Script项目。

它能做什么

需要提前了解的重要限制： 使用apps_script_update_file / apps_script_update_content推送代码只会更新可编辑的项目，与在脚本编辑器中输入并保存的效果相同。它不会自动更新任何已部署的内容（例如，已上线的Web应用网址，或绑定到特定部署版本的触发器）。要使更改生效，请创建版本（apps_script_create_version），然后在Apps Script编辑器中进行重新部署——此服务器特意不涉及部署发布，因为这是一个更重要的操作，前几次最好手动完成。

1. 一次性Google Cloud设置（请先执行此步骤）

你需要一个已启用Apps Script API并配置了OAuth客户端的Google Cloud项目。这大约需要5分钟。

1. 创建或选择一个Google Cloud项目 前往 https://console.cloud.google.com/projectcreate 创建一个项目（任何名称都可以——例如"kwarab-apps-script-mcp"）。如果你已有用于其他Kwara/Ekiti工作的GCP项目，也可以重复使用。

2. 在项目中启用Apps Script API 前往 https://console.cloud.google.com/apis/library/script.googleapis.com，选择你的项目，然后点击启用。

3. 配置OAuth同意屏幕 前往 https://console.cloud.google.com/apis/credentials/consent

   • 用户类型：外部（除非你有Google Workspace组织，那么选择内部也可以）

   • 填写应用名称（例如"Apps Script MCP"），你的电子邮件作为支持联系信息

   • 范围：你可以在此处跳过添加范围——服务器会直接请求它们

   • 测试用户：添加你自己的Google账户电子邮件（应用处于“测试”状态时需要，个人/内部使用则可以）

4. 创建OAuth客户端 前往 https://console.cloud.google.com/apis/credentials

   • 点击创建凭据 → OAuth客户端ID

   • 应用类型：桌面应用

   • 任意命名（例如"Apps Script MCP Desktop"）

   • 点击创建，然后下载JSON

5. 将下载的文件保存为项目根目录（与本README相同目录）下的credentials.json。不要提交或分享此文件——它标识了你的OAuth客户端（不是你的个人账户，但仍需保密）。

6. 为你自己的Google账户启用Apps Script API 这与第2步不同（第2步为项目启用API；此步骤为拥有/编辑脚本的Google账户启用API）。前往 https://script.google.com/home/usersettings 并打开**“Google Apps Script API”**。

2. 安装并授权

npm install
npm run build
npm run authorize

npm run authorize 会打开你的浏览器，要求你使用有权访问Kwara疾病监测Apps Script项目的Google账户登录，并请求你批准访问。批准后，它会将刷新令牌保存到此文件夹中的token.json——你只需执行一次（如果撤销访问权限或切换Google账户，请重新运行）。

**如果浏览器没有自动打开：**终端会打印一个URL——将其复制粘贴到任何浏览器中，批准，然后你会被重定向回本地正在监听的localhost；终端会确认成功。

3. 将其连接到Claude

选项A：本地（stdio）——Claude Code / Claude Desktop

将其添加到你的MCP配置中（例如claude_desktop_config.json或你的Claude Code MCP设置）：

{
  "mcpServers": {
    "apps-script": {
      "command": "node",
      "args": ["/absolute/path/to/apps-script-mcp-server/dist/index.js"]
    }
  }
}

添加后重启Claude Desktop / Claude Code。你应该会看到apps-script列在已连接的MCP服务器中，并带有apps_script_update_file等工具可用。

选项B：远程（HTTP），例如托管在Render上

服务器也可以作为独立HTTP服务运行——设置TRANSPORT=http。这就是本仓库中的render.yaml自动配置的内容。请参阅下面的部署到Render。

远程服务器可以被任何拥有其URL的人访问，因此对/mcp的每个请求都必须包含与MCP_SERVER_TOKEN环境变量匹配的Bearer令牌，你设置了该变量：

Authorization: Bearer <your MCP_SERVER_TOKEN value>

在Claude的远程MCP连接器设置中，添加服务器URL（https://<your-service>.onrender.com/mcp）并设置该标头。/healthz故意不进行身份验证，以便Render的健康检查可以访问它。

部署到Render

此仓库包含一个render.yaml蓝图，因此Render可以创建服务并预先填充大部分设置。

1. 在Render仪表板中：新建 → 蓝图，如果尚未连接，请连接你的GitHub账户，然后选择此仓库。Render将读取render.yaml。

2. Render会提示你输入标记为sync: false的环境变量：

   • MCP_SERVER_TOKEN——生成一个长的随机字符串（例如openssl rand -hex 32）。这是Claude必须作为Bearer令牌发送的内容。

   • GOOGLE_OAUTH_CLIENT_ID、GOOGLE_OAUTH_CLIENT_SECRET、GOOGLE_OAUTH_REFRESH_TOKEN——先在本地生成这些（上述第1-2步，包括npm run authorize），然后打开生成的token.json，将client_id、client_secret和refresh_token复制到Render的环境变量字段中。Render永远不会获得浏览器，因此这种无头凭据路径替代了本地的npm run authorize步骤。

3. 部署。上线后，MCP端点为https://<your-service>.onrender.com/mcp。

4. 在免费计划中，Render会在不活动后关闭服务——空闲后的第一个请求会变慢（冷启动），因为需要重新启动。

4. 使用它

你需要Kwara疾病监测Apps Script项目的脚本ID。通过打开项目https://script.google.com，并从URL中复制ID来找到它：

https://script.google.com/home/projects/<THIS_IS_THE_SCRIPT_ID>/edit

（如果Apps Script绑定到KWARAB Google Sheet而不是独立存在，请打开表格 → 扩展程序 → Apps Script 进入相同的编辑器和URL。）

然后，在连接了此MCP服务器的Claude对话中，你可以说：

• “显示脚本<scriptId>中当前的Code.gs”

• “更新Code.gs中的sendAlertEmail函数，使其同时抄送DSNO主管”

• “推送这个新的Utils.gs文件，包含这些辅助函数：...”

• “创建一个名为‘添加AFP EPID自动组合逻辑’的新版本”

安全说明

• credentials.json和token.json都授予对你可编辑的Apps Script项目的访问权限。请将它们排除在版本控制之外（已包含.gitignore），不要共享它们。

• 请求的OAuth范围（script.projects、script.deployments）不包括Gmail、Sheets或Drive访问权限，仅限于读取/写入脚本项目内容和检查部署所需的范围。

• 要随时撤销访问权限：https://myaccount.google.com/permissions → 找到你在上述第4步中设置的OAuth客户端名称 → 移除访问权限。之后删除token.json。

故障排除