apps-script-mcp-server

Claude が Google Apps Script（.gs、.html、appsscript.json）のコードを直接スクリプトプロジェクトに読み書きできるようにする MCP サーバーです。もう手動で Apps Script エディタにコードをコピペする必要はありません。

Kwara 疾病監視システム（KWARAB ダッシュボード） 向けに構築されていますが、編集権限のある任意の Apps Script プロジェクトで動作します。

できること

事前に知っておくべき重要な制限事項： apps_script_update_file / apps_script_update_content でコードをプッシュすると、編集可能なプロジェクトが更新されます。これはスクリプトエディタで入力して保存するのと同じです。すでにデプロイされているもの（例：公開中のウェブアプリ URL、特定のデプロイバージョンにバインドされたトリガー）は自動的には更新されません。変更を公開するには、バージョンを作成し（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 アカウントに対して有効にします）。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 を再起動します。接続された MCP サーバーの中に apps-script が表示され、apps_script_update_file などのツールが利用可能になります。

オプション B：リモート（HTTP）、例：Render でホスト

サーバーはスタンドアロンの HTTP サービスとしても実行できます。TRANSPORT=http を設定してください。これはこのリポジトリの render.yaml で自動的に構成されます。以下の Render へのデプロイ を参照してください。

リモートサーバーは URL を知っている誰でもアクセスできます。そのため、/mcp へのすべてのリクエストには、設定した MCP_SERVER_TOKEN 環境変数と一致するベアラートークンを含める必要があります：

Authorization: Bearer <your MCP_SERVER_TOKEN value>

Claude のリモート MCP コネクタ設定で、サーバー URL（https://<your-service>.onrender.com/mcp）を追加し、そのヘッダーを設定します。/healthz は意図的に認証なしにしているため、Render のヘルスチェックが到達できます。

Render へのデプロイ

このリポジトリには render.yaml ブループリントが含まれているため、Render はほとんどの設定が事前に入力された状態でサービスを作成できます。

1. Render ダッシュボードで：New → Blueprint、まだの場合は GitHub アカウントを接続し、このリポジトリを選択します。Render が render.yaml を読み取ります。

2. Render は sync: false とマークされた環境変数を要求します：

   • MCP_SERVER_TOKEN — 長いランダムな文字列を作成します（例：openssl rand -hex 32）。これは Claude がベアラートークンとして送信する必要があるものです。

   • 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 シートにバインドされている場合、スタンドアロンではなく、シートを開いて → 拡張機能 → Apps Script で同じエディタと URL にアクセスできます。）

その後、この MCP サーバーが接続された Claude の会話で、次のように指示できます：

• 「スクリプト <scriptId> の現在の Code.gs を表示して」

• 「Code.gs の sendAlertEmail 関数を更新して、DSNO スーパーバイザーも CC に追加して」

• 「この新しい Utils.gs ファイルを次のヘルパー関数と一緒にプッシュして：...」

• 「'Add AFP EPID auto-compose logic' という名前の新しいバージョンを作成して」

セキュリティに関する注意

• credentials.json と token.json はどちらも、編集可能な Apps Script プロジェクトへのアクセスを許可します。バージョン管理から除外し（.gitignore が含まれています）、共有しないでください。

• 要求される OAuth スコープ（script.projects、script.deployments）には、スクリプトプロジェクトのコンテンツの読み書きとデプロイの検査に必要な範囲を超える Gmail、シート、ドライブへのアクセスは含まれません。

• いつでもアクセスを取り消すには：https://myaccount.google.com/permissions → 上記手順 4 で設定した OAuth クライアント名を見つける → アクセスを削除。その後 token.json を削除します。

トラブルシューティング