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文件。