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 と包括的に連携し、Claude Desktop、Cline を導入した VS Code、Postman など、あらゆる MCP 対応クライアントを通じて、スクリプトプロジェクト、デプロイ、バージョン、実行を管理できます。

📋 目次

• 概要
• 機能
• 前提条件
• クイックスタートガイド
• 詳細なセットアップ手順
• 利用可能なツール
• スクリプトの認可
• MCP クライアントの設定
• トラブルシューティング
• 高度な使い方

🌟 概要

この MCP サーバーを使用すると、以下を通じて Google Apps Script をシームレスに操作できます。

• ✅ OAuth 2.0 認証 - 自動更新機能を備えた安全なトークン管理
• ✅ 16 種類の包括的なツール - Google Apps Script API を全面的にカバー
• ✅ MCP プロトコル準拠 - Claude Desktop、VS Code、その他の MCP クライアントで動作
• ✅ 安全なトークン保存 - リフレッシュトークンを OS ごとに安全に保存
• ✅ トークンの自動更新 - トークンの有効期限切れを自動的に処理
• ✅ 詳細なログ記録 - 包括的なエラー処理とデバッグ

🎥 デモ動画

Google Apps Script MCP サーバーの動作をご覧ください。VS Code AI Agent を通じて、プロジェクトの作成、デプロイの管理、スクリプトの実行を行います。

🚀 機能

主な機能

• プロジェクト管理: 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

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. **「新しいプロジェクト」**をクリックするか、既存のプロジェクトを選択します
4. 新しいプロジェクトを作成する場合：
   • プロジェクト名を入力します（例：「Google Apps Script MCP」）
   • プロジェクト ID を控えておきます（後で必要になります）
   • **「作成」**をクリックします

1.2 必要な API を有効にする

1. Google Cloud Console で、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 が有効になるまで待ちます（数分かかることがあります）

1.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. **「保存して次へ」**をクリックします

1.4 OAuth 2.0 認証情報を作成する

1. API とサービス → 認証情報に移動します
2. 「＋認証情報を作成」 → **「OAuth 2.0 クライアント ID」**をクリックします
3. アプリケーションの種類として**「ウェブアプリケーション」**を選択します
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

ステップ 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 をクライアント ID に置き換えます
• your_client_secret_here をクライアント シークレットに置き換えます

ステップ 3：OAuth 認証をセットアップする

3.1 OAuth セットアップを実行する

OAuth セットアップスクリプトを実行します：

npm run setup-oauth

このスクリプトの処理内容：

1. http://localhost:3001 で一時的なローカルサーバーを起動します
2. デフォルトのブラウザーで Google の認証ページを開きます
3. アプリケーションへの権限付与を求めます
4. コールバック URL を介して認証コードを取得します
5. 認証コードをアクセストークンと更新トークンに交換します
6. OS の認証情報ストアに更新トークンを安全に保存します
7. テスト用の API 呼び出しを行い、トークンをテストします

3.2 権限を付与する

ブラウザーが開いたら：

1. Google アカウントを選択します（追加したテストユーザーである必要があります）
2. 要求されている権限を確認します：
   • Google Apps Script プロジェクトの表示と管理
   • スクリプトの実行と指標の表示
   • スクリプトのデプロイへのアクセス
3. **「続行」または「許可」**をクリックします
4. 次のメッセージが表示されます：「OAuth の設定が正常に完了しました！」

3.3 トークンの保存を確認する

セットアッププロセスでは、トークンが安全に保存されます：

• Windows：Windows 資格情報マネージャー
• macOS：キーチェーンアクセス
• 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 サーバーでは、Google Apps Script を管理するための包括的なツールを 16 個提供しています：

プロジェクト管理ツール

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（任意）：1 ページあたりのバージョン数
• pageToken（任意）：ページネーション用のトークン

デプロイ管理ツール

8. script-projects-deployments-create

目的：Google Apps Script プロジェクトのデプロイを作成します パラメーター：

• scriptId（必須）：デプロイするスクリプトの ID
• versionNumber（必須）：デプロイするバージョン番号
• manifestFileName（必須）：マニフェストファイルの名前
• description（必須）：デプロイの説明

使用例：スクリプトをウェブアプリまたは API 実行可能ファイルとしてデプロイします

{
  "scriptId": "1ABC123def456GHI789jkl",
  "versionNumber": 3,
  "manifestFileName": "appsscript.json",
  "description": "Production deployment v1.2"
}

注：デプロイで DriveApp や SpreadsheetApp などの Google サービスを使用する場合、ウェブアプリが応答する前に Apps Script エディタでスクリプトを手動で承認する必要があります。スクリプトの承認を参照してください。

9. script-projects-deployments-get

目的：特定のデプロイの詳細を取得します パラメーター：

• scriptId（必須）：スクリプトプロジェクトの ID
• deploymentId（必須）：デプロイの ID

10. script-projects-deployments-list

目的：スクリプトプロジェクトのすべてのデプロイメントを一覧表示します パラメーター：

• scriptId（必須）：スクリプトプロジェクトの ID
• pageSize（任意）：1 ページあたりのデプロイメント数

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（任意）：1 ページあたりのプロセス数
• 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 サービスを使用する場合、デプロイしたウェブアプリが正しく応答するには、事前に手動で認可する必要があります。MCP サーバーの API デプロイでは、Google の OAuth 同意フローは開始されません。

デプロイしたウェブアプリに「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 サービスを呼び出す任意の関数（例：doGet）で、実行をクリックします。

3. メッセージが表示されたら、権限を確認をクリックします。

4. Google OAuth の同意フローを完了します。

   • Google アカウントを選択します
   • 詳細 → {project name}（安全ではないページ）に移動をクリックします
   • 許可をクリックします

5. これで、デプロイしたウェブアプリが正しく動作します。

**注：**これは Google Apps Script プラットフォームの要件であり、API 経由で回避することはできません。

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

MCP サーバー（mcpServer.js）は、自動化された API ツールを Claude Desktop や Postman Desktop Application などの MCP 対応クライアントに公開します。まず Postman でサーバーをテストしてから、LLM での使用に進むことをおすすめします。

ステップ 1：最新の Postman Desktop Application を https://www.postman.com/downloads/ からダウンロードします。

ステップ 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 サーバーを 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 のセットアップ

Step 1：前のセクションで確認したフルパスを控えます。

Step 2：Claude Desktop を開き、次の場所に移動します。

• Settings → Developers → Edit Config

Step 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"
      }
    }
  }
}

Step 4：OAuth 認証情報を .env ファイルの実際の値に置き換えます。

Step 5：設定を保存し、Claude Desktop を再起動します。

Step 6：Claude Desktop で MCP サーバーの横に緑色の丸いインジケーターが表示されていることを確認し、接続を確認します。

📝 VS Code のセットアップ（Cline/MCP 拡張機能）

VS Code では、Cline などの拡張機能や、MCP 互換の拡張機能を使って MCP サーバーを利用できます。

Cline 拡張機能を使用する

Step 1：VS Code Marketplace から Cline 拡張機能 をインストールします。

Step 2：VS Code の設定を開きます（Windows/Linux では Ctrl+,、macOS では Cmd+,）。

Step 3：設定で「Cline」または「MCP」を検索します。

Step 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

🔑 忘れずに以下を行ってください。

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 ではバックスラッシュを 2 つ使用）を確認します。
• 設定を変更した後、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 アプリの認証情報が変更されていないことを確認します。
• Google Cloud Console で OAuth アプリが引き続き有効であることを確認します。

10. スクリプト実行権限のエラー

問題：スクリプトを実行できないか、プロジェクトにアクセスできません。 解決方法：

• Google アカウントに Apps Script プロジェクトへのアクセス権があることを確認します。
• スクリプトがアカウントと共有されていることを確認します。
• 必要なスコープが付与されていることを確認します。
• スクリプトを実行するには、スクリプトがデプロイされ、実行可能であることを確認します。

11. デプロイ済みのウェブアプリで「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 };

Server-Sent Events（SSE）モード

ウェブインターフェースとリアルタイムで通信する場合：

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

リクエストのバッチ処理

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

// 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 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 の下でライセンスされています。詳しくは LICENSE ファイルをご覧ください。