Google Appscript MCP Server

🚀 Google Apps Script MCP Server

Google Apps Script MCP (Model Context Protocol) Serverは、Google Apps Script APIとの包括的な統合を提供します。これにより、Claude Desktop、VS Code with Cline、PostmanなどのMCP互換クライアントを通じて、スクリプトプロジェクト、デプロイメント、バージョン、および実行を管理できます。

🚀 クイックスタート

このMCPサーバーを使い始めるには、以下の手順に従ってください。

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のセットアップ

以下の詳細なセットアップ手順に従ってください。

4. OAuthセットアップの実行

npm run setup-oauth

5. サーバーのテスト

npm start

✨ 主な機能

コア機能

• プロジェクト管理：Google Apps Scriptプロジェクトの作成、取得、および更新
• デプロイメント管理：スクリプトのデプロイメントの作成、一覧表示、更新、および削除
• バージョン管理：スクリプトのバージョンの作成と管理
• コンテンツ管理：スクリプトのコンテンツとファイルの取得と更新
• プロセス監視：スクリプトの実行プロセスの一覧表示と監視
• メトリクスアクセス：スクリプトの実行メトリクスと分析情報の取得
• スクリプト実行：Google Apps Script関数のリモート実行

セキュリティ機能

• OAuth 2.0フロー：完全なGoogle OAuthの実装
• 安全なトークン保管：リフレッシュトークンをOS固有の安全なストレージに保管
• 自動トークン更新：手動でのトークン管理が不要
• 環境変数サポート：安全な資格情報の設定

📦 インストール

前提条件

開始する前に、以下が必要です。

• Node.js (v18以上が必要、v20以上が推奨) - ここからダウンロード
• npm (Node.jsに含まれています)
• Google Cloud ConsoleにアクセスできるGoogleアカウント
• リポジトリをクローンするためのGit

詳細なセットアップ手順

ステップ1: クローンとインストール

リポジトリのクローン

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

依存関係のインストール

npm install

ステップ2: Google Cloud Consoleのセットアップ

2.1 Google Cloudプロジェクトの作成または選択

1. Google Cloud Consoleにアクセスします。
2. 上部のプロジェクトドロップダウンをクリックします。
3. "新しいプロジェクト" をクリックするか、既存のプロジェクトを選択します。
4. 新しいプロジェクトを作成する場合：
   • プロジェクト名を入力します（例："Google Apps Script MCP"）。
   • プロジェクトIDをメモします（後で必要になります）。
   • "作成" をクリックします。

2.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. "有効にする" をクリックします。
4. APIが有効になるまで待ちます（数分かかる場合があります）。

2.3 OAuth同意画面の構成

1. APIs & Services → OAuth consent screenに移動します。
2. Externalを選択します（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. "更新" をクリックします。

テストユーザーの追加（Externalアプリの場合）

1. "ユーザーの追加" をクリックします。
2. あなたのGmailアドレスをテストユーザーとして追加します。
3. "保存して続行" をクリックします。

2.4 OAuth 2.0資格情報の作成

1. APIs & Services → Credentialsに移動します。
2. "+ CREATE CREDENTIALS" → "OAuth 2.0 Client IDs" をクリックします。
3. アプリケーションの種類として、"Web application" を選択します。
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 Configuration
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. リフレッシュトークンをOSの資格情報ストアに安全に保存します。
7. テストAPI呼び出しを行って、トークンをテストします。

4.2 アクセス許可の付与

ブラウザが開いたら：

1. あなたのGoogleアカウントを選択します（追加したテストユーザーである必要があります）。
2. 要求されているアクセス許可を確認します。
   • Google Apps Scriptプロジェクトを表示および管理する
   • スクリプトの実行とメトリクスを表示する
   • スクリプトのデプロイメントにアクセスする
3. "続行" または "許可" をクリックします。
4. 次のメッセージが表示されるはずです："OAuth setup completed successfully!"

4.3 トークン保管の検証

セットアッププロセスは、トークンを安全に保管します。

• Windows：Windows Credential Manager
• macOS：Keychain Access
• Linux：Secret Service 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

💻 使用例

基本的な使用法

// 新しい自動化タスク用のスクリプトを作成する
{
  "title": "My Automation Script",
  "parentId": "1234567890"
}

高度な使用法

// 新しいバージョンを作成してデプロイする
{
  "scriptId": "1ABC123def456GHI789jkl",
  "versionNumber": 3,
  "manifestFileName": "appsscript.json",
  "description": "Production deployment v1.2"
}

📚 ドキュメント

利用可能なツール

このMCPサーバーは、Google Apps Script管理のための16の包括的なツールを提供します。

プロジェクト管理ツール

• script-projects-create：新しいGoogle Apps Scriptプロジェクトを作成します。
• script-projects-get：Google Apps Scriptプロジェクトのメタデータを取得します。
• script-projects-get-content：Google Apps Scriptプロジェクトのコンテンツを取得します。
• script-projects-update-content：Google Apps Scriptプロジェクトのコンテンツを更新します。

バージョン管理ツール

• script-projects-versions-create：Google Apps Scriptプロジェクトの新しいバージョンを作成します。
• script-projects-versions-get：特定のスクリプトバージョンの詳細を取得します。
• script-projects-versions-list：スクリプトプロジェクトのすべてのバージョンを一覧表示します。

デプロイメント管理ツール

• script-projects-deployments-create：Google Apps Scriptプロジェクトのデプロイメントを作成します。
• script-projects-deployments-get：特定のデプロイメントの詳細を取得します。
• script-projects-deployments-list：スクリプトプロジェクトのすべてのデプロイメントを一覧表示します。
• script-projects-deployments-update：既存のデプロイメントを更新します。
• script-projects-deployments-delete：デプロイメントを削除します。

実行と監視ツール

• script-scripts-run：Google Apps Script関数を実行します。
• script-processes-list：スクリプトプロジェクトの実行プロセスを一覧表示します。
• script-processes-list-script-processes：追加のフィルタリングオプションでスクリプトプロセスを一覧表示する代替方法です。
• script-projects-get-metrics：スクリプトプロジェクトの実行メトリクスと分析情報を取得します。

ツールカテゴリの概要

カテゴリ	ツール	目的
プロジェクト管理	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を使用して自動化ワークフローをトリガーします。

PostmanでMCPサーバーをテストする

MCPサーバー (mcpServer.js) は、自動化されたAPIツールをClaude DesktopやPostman Desktop ApplicationなどのMCP互換クライアントに公開します。最初にPostmanでサーバーをテストし、その後LLMで使用することをお勧めします。

ステップ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

新しいPostman MCPリクエストのコマンドとして、nodeコマンドに続けてmcpServer.jsの完全なパスを使用します。次に、Connectボタンをクリックします。サーバーを生成する前に選択したツールのリストが表示されるはずです。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 Desktopのセットアップ

ステップ1：前のセクションの完全なパスをメモします。

ステップ2：Claude Desktopを開き、次の場所に移動します。

• Settings → Developers → Edit Config

ステップ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：.envファイルから実際の値でOAuth資格情報を置き換えます。

ステップ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 → "Preferences: Open Settings (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を実行したことを確認します。

🔧 技術詳細

一般的な問題と解決策

1. "Command not found" または "Node not found" エラー

問題：MCPクライアントがNode.js実行可能ファイルを見つけられません。 解決策：

• Node.jsが正しくインストールされ、PATHに含まれていることを確認します。
• Node.js実行可能ファイルの絶対パスを使用することをお勧めします。
• node --versionを使用して、Node.jsのバージョンが18以上であることを確認します。
• Windowsでは、複数のNode.jsバージョンがインストールされているかどうかを確認します。

2. "fetch is not defined" エラー

問題：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. "Authorization Error: Access blocked"

問題：Google OAuth同意画面の構成に問題があります。 解決策：

• アプリが"External"ユーザー用に構成されていることを確認します。
• OAuth同意画面であなたのGmailアドレスをテストユーザーとして追加します。
• すべての必要なスコープが追加されていることを確認します。
• OAuth同意画面が適切に公開されていることを確認します。

5. MCPサーバーがClaude Desktopに表示されない

問題：構成ファイルの構文またはパスに問題があります。 解決策：

• 構成ファイルの構文を確認します（有効な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を使用しているプロセスを終了させます。

  # macOS/Linuxでポート3001を使用しているプロセスを見つける
  lsof -i :3001
  
  # Windowsでポート3001を使用しているプロセスを見つける
  netstat -ano | findstr :3001
  
  # macOS/Linuxでプロセスを終了させる
  kill -9 <PID>
  
  # Windowsでプロセスを終了させる
  taskkill /PID <PID> /F
  

• または、oauth-setup.jsで一時的にポートを変更します。

9. "Token expired" または "Invalid credentials" エラー

問題：OAuthトークンが期限切れまたは無効です。 解決策：

• OAuthセットアップを再実行します：npm run setup-oauth
• 保存されているトークンをクリアし、再認証します。
• あなたのOAuthアプリの資格情報が変更されていないことを確認します。
• Google Cloud ConsoleでOAuthアプリがまだアクティブであることを確認します。

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クライアントの構成（シークレットを除く）

高度な使用法

環境変数

コア構成

# 必須の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 };

Server-Sent Events (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ヘルパーは、アクセストークンを自動的にメモリにキャッシュし、必要に応じて更新します。

リクエストのバッチ処理

複数の操作については、可能な限りリクエストをバッチ処理することを検討してください。

// 複数の個別の呼び出しの代わりに
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スクリプト

# 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

例の出力：

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 Generatorにアクセスします。
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 Generatorを訪問して、更新情報を確認します。

貢献

貢献は歓迎されます！次の手順に従ってください。

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. 新しい機能に対するテストを追加します。
4. プルリクエストを送信します。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。