mcp-google-sheets

🤔 これは何ですか？

mcp-google-sheetsは、Python ベースの MCP サーバーで、MCP 対応クライアント（Claude Desktop など）と Google Sheets API 間のブリッジとして機能します。定義されたツールセットを使用して Google スプレッドシートを操作できるため、AI を活用した強力な自動化とデータ操作ワークフローを実現できます。

🚀 クイックスタート（ uvxを使用）

基本的に、サーバーはuvx mcp-google-sheetsという 1 行で実行されます。

このコマンドは、必要に応じて最新のコードを自動的にダウンロードして実行します。ただし、Google Cloud の設定にはかなり多くの手順が必要ですので、以下の手順をお読みください。

1. ☁️ 前提条件: Google Cloud のセットアップ
   • まずGoogle Cloud Platformの認証情報を設定し、必要なAPIを有効にする必要があります。サービスアカウントの使用を強くお勧めします。
   • ➡️ 以下の詳細な Google Cloud Platform セットアップガイドにジャンプします。
2. 🐍 uvをインストールする
   • uvx 、高速なPythonパッケージインストーラー兼リゾルバーであるuvの一部です。まだインストールしていない場合は、以下の手順でインストールしてください。
     # macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # Or using pip: # pip install uv
     必要に応じて、インストーラーの出力の指示に従って、 uv PATH に追加します。
3. 🔑 必須の環境変数を設定する（サービス アカウントを推奨）
   • サーバーに認証方法を伝える必要があります。ターミナルで以下の変数を設定してください。
   • （Linux/macOS）
     # Replace with YOUR actual path and folder ID from the Google Setup step export SERVICE_ACCOUNT_PATH="/path/to/your/service-account-key.json" export DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"
   • （Windows コマンド）
     set SERVICE_ACCOUNT_PATH="C:\path\to\your\service-account-key.json" set DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"
   • (Windows PowerShell)
     $env:SERVICE_ACCOUNT_PATH = "C:\path\to\your\service-account-key.json" $env:DRIVE_FOLDER_ID = "YOUR_DRIVE_FOLDER_ID"
   • ➡️ その他のオプション (OAuth、 CREDENTIALS_CONFIG ) については、詳細な認証と環境変数を参照してください。
4. 🏃 サーバーを実行してください!
   • uvx``mcp-google-sheetsの最新バージョンを自動的にダウンロードして実行します。
     uvx mcp-google-sheets
   • サーバーが起動し、準備完了を示すログが出力されます。
5. 🔌 MCPクライアントを接続する
   • 実行中のサーバーに接続するようにクライアント (例: Claude Desktop) を構成します。
   • 使用するクライアントによっては、クライアント側でサーバーを起動できるため、手順4は不要になる場合があります。ただし、正しく設定されていることを確認するために、手順4をテスト実行することをお勧めします。
   • ➡️ 例については、 Claude Desktop での使用法を参照してください。

準備完了です！MCP クライアント経由でコマンドの発行を開始してください。

✨ 主な特徴

• シームレスな統合: Google ドライブおよび Google スプレッドシート API に直接接続します。
• **包括的なツール:**幅広い操作 (CRUD、リスト、バッチ処理、共有、フォーマットなど) を提供します。
• 柔軟な認証: サービス アカウント (推奨) 、OAuth 2.0、環境変数を介した直接的な資格情報挿入をサポートします。
• 簡単な導入: uvx (ゼロインストール感覚) で即座に実行するか、 uvを使用して開発用にクローンを作成します。
• AI 対応: MCP 対応クライアントで使用するために設計されており、自然言語によるスプレッドシートのインタラクションを可能にします。

🛠️ 利用可能なツールとリソース

このサーバーは、Google スプレッドシートを操作するための次のツールを公開します。

（入力パラメータは、特に指定がない限り、通常は文字列です）

• list_spreadsheets : 構成されたドライブ フォルダ (サービス アカウント) 内のスプレッドシート、またはユーザーがアクセス可能なスプレッドシート (OAuth) を一覧表示します。
  • *戻り値:*オブジェクトのリスト[{id: string, title: string}]
• create_spreadsheet : 新しいスプレッドシートを作成します。
  • title (文字列): 希望するタイトル。
  • 戻り値: spreadsheetIdを含むスプレッドシート情報を含むオブジェクト。
• get_sheet_data : シート内の範囲からデータを読み取ります。
  • spreadsheet_id （文字列）
  • sheet (文字列): シートの名前。
  • range （オプションの文字列）：A1表記（例： 'A1:C10' 、 'Sheet1!B2:D' ）。省略した場合はシート全体を読み取ります。
  • *戻り値:*セル値の 2D 配列。
• update_cells : 特定の範囲にデータを書き込みます。既存のデータは上書きされます。
  • spreadsheet_id （文字列）
  • sheet （文字列）
  • range （文字列）：A1表記。
  • data (2D 配列): 書き込む値。
  • *戻り値:*結果オブジェクトを更新します。
• batch_update_cells : 1 回の API 呼び出しで複数の範囲を更新します。
  • spreadsheet_id （文字列）
  • sheet （文字列）
  • ranges (オブジェクト): 範囲文字列 (A1 表記) を値の 2 次元配列にマッピングする辞書{ "A1:B2": [[1, 2], [3, 4]], "D5": [["Hello"]] } 。
  • *戻り値:*バッチ更新結果オブジェクト。
• add_rows : シートの末尾 (データのある最後の行の後) に行を追加します。
  • spreadsheet_id （文字列）
  • sheet （文字列）
  • data (2D 配列): 追加する行。
  • *戻り値:*結果オブジェクトを更新します。
• list_sheets : スプレッドシート内のすべてのシート名を一覧表示します。
  • spreadsheet_id （文字列）
  • *戻り値:*シート名文字列のリスト["Sheet1", "Sheet2"] 。
• create_sheet : スプレッドシートに新しいシート (タブ) を追加します。
  • spreadsheet_id （文字列）
  • title (文字列): 新しいシートの名前。
  • *戻り値:*新しいシート プロパティ オブジェクト。
• get_multiple_sheet_data : 1 回の呼び出しで、異なる可能性のあるスプレッドシートの複数の範囲からデータを取得します。
  • queries （オブジェクトの配列）：各オブジェクトには、 spreadsheet_id 、 sheet 、 rangeが必要です。 [{spreadsheet_id: 'abc', sheet: 'Sheet1', range: 'A1:B2'}, ...] 。
  • *戻り値:*クエリ パラメータと取得されたdata 、またはerrorを含むオブジェクトのリスト。
• get_multiple_spreadsheet_summary : 複数のスプレッドシートのタイトル、シート名、ヘッダー、最初の数行を取得します。
  • spreadsheet_ids （文字列の配列）
  • rows_to_fetch (オプションの整数、デフォルトは 5): プレビューする行数 (ヘッダーを含む)。
  • *戻り値:*各スプレッドシートの概要オブジェクトのリスト。
• share_spreadsheet : 指定されたユーザー/メールおよびロールとスプレッドシートを共有します。
  • spreadsheet_id （文字列）
  • recipients （オブジェクトの配列）： [{email_address: 'user@example.com', role: 'writer'}, ...] 。ロール： reader 、 commenter 、 writer 。
  • send_notification (オプションのブール値、デフォルトは True): 電子メール通知を送信します。
  • 戻り値: successesとfailuresリストを含む辞書。
• add_columns : シートに列を追加します。 (実装されている場合はパラメータを確認してください)
• copy_sheet : スプレッドシート内のシートを複製します。 (実装されている場合はパラメータを確認してください)
• rename_sheet : 既存のシートの名前を変更します。 (実装されている場合はパラメータを確認してください)

MCP リソース:

• spreadsheet://{spreadsheet_id}/info : Google スプレッドシートに関する基本的なメタデータを取得します。
  • *戻り値:*スプレッドシート情報を含む JSON 文字列。

☁️ Google Cloud Platform のセットアップ（詳細）

サーバーを実行する前にこの設定が必要です。

1. GCP プロジェクトを作成/選択する: Google Cloud Consoleに移動します。
2. APIを有効にする： 「APIとサービス」→「ライブラリ」に移動し、以下のAPIを検索して有効にします。
   • Google Sheets API
   • Google Drive API
3. **資格情報の構成:**以下の認証方法のいずれかを選択する必要があります (サービス アカウントを推奨)。

🔑 認証と環境変数（詳細）

Google API にアクセスするにはサーバーに認証情報が必要です。次のいずれかの方法を選択してください。

方法 A: サービス アカウント (サーバー/オートメーションに推奨) ✅

• **理由：**ヘッドレス（ブラウザ不要）、安全、サーバー環境に最適。簡単に期限切れになることはありません。
• 手順:
  1. サービス アカウントを作成します。GCP Console -> 「IAM と管理」 -> 「サービス アカウント」。
     • 「+ サービスアカウントを作成」をクリックします。名前を付けます（例： mcp-sheets-service ）。
     • 役割の付与: 広範なアクセスを許可するにはEditor役割を追加し、より厳しい権限を許可するにはより詳細な役割 ( roles/drive.fileや特定のスプレッドシートの役割など) を追加します。
     • 「完了」をクリックします。アカウントを見つけて、「アクション」（⋮）→「キーの管理」をクリックします。
     • 「キーの追加」→「新しいキーの作成」→ 「JSON 」→「作成」をクリックします。
     • JSON キー ファイルをダウンロードして安全に保存します。
  2. Google ドライブ フォルダを作成して共有する:
     • Google ドライブでフォルダを作成します（例：「AI 管理シート」）。
     • URL からフォルダー IDをメモします: https://drive.google.com/drive/folders/THIS_IS_THE_FOLDER_ID 。
     • フォルダを右クリック -> 「共有」 -> 「共有」。
     • サービス アカウントのメール アドレスを入力します (JSON ファイルclient_emailから)。
     • 編集者権限を付与します。「通知」のチェックを外します。「共有」をクリックします。
  3. 環境変数を設定する:
     • SERVICE_ACCOUNT_PATH : ダウンロードした JSON キー ファイルへのフル パス。
     • DRIVE_FOLDER_ID : 共有 Google ドライブ フォルダの ID。 (OS 固有の例については、 Ultra Quick Start を参照してください)

方法 B: OAuth 2.0 (インタラクティブ / 個人使用) 🧑‍💻

• **なぜでしょうか?**対話型ブラウザログインが可能な個人使用またはローカル開発向けです。
• 手順:
  1. OAuth同意画面の設定： GCP Console -> 「APIとサービス」 -> 「OAuth同意画面」。「外部」を選択し、必要な情報を入力し、スコープ（ .../auth/spreadsheets 、 .../auth/drive ）を追加し、必要に応じてテストユーザーを追加します。
  2. OAuthクライアントIDを作成： GCP Consoleで、「APIとサービス」→「認証情報」を選択します。「+認証情報を作成」→「OAuthクライアントID」→タイプ：デスクトップアプリ。名前を付けて「CREATE」と入力します。JSONをダウンロードします。
  3. 環境変数を設定する:
     • CREDENTIALS_PATH : ダウンロードした OAuth 資格情報 JSON ファイルへのパス (デフォルト: credentials.json )。
     • TOKEN_PATH : 初回ログイン後にユーザーのリフレッシュトークンを保存するパス（デフォルト： token.json ）。書き込み可能である必要があります。

方法 C: 直接的な資格情報注入（上級）🔒

• 理由： Docker、Kubernetes、CI/CDといった、ファイル管理が難しいものの、環境変数は簡単かつ安全に管理できる環境で役立ちます。ファイルシステムへのアクセスを回避できます。
• **どうやって？**資格情報ファイルへのパスを指定する代わりに、Base64 でエンコードされたファイルの内容を環境変数に直接指定します。
• 手順:
  1. 認証情報のJSONファイル（サービスアカウントキーまたはOAuthクライアントIDファイル）を取得します。ここではyour_credentials.jsonとします。
  2. Base64 文字列を生成します。
     • (Linux/macOS): base64 -w 0 your_credentials.json
     • (Windows PowerShell):
       $filePath = "C:\path\to\your_credentials.json"; # Use actual path $bytes = [System.IO.File]::ReadAllBytes($filePath); $base64 = [System.Convert]::ToBase64String($bytes); $base64 # Copy this output
     • **(注意):**信頼できないオンライン エンコーダーに機密の資格情報を貼り付けないようにしてください。
  3. 環境変数を設定します。
     • CREDENTIALS_CONFIG : この変数を、先ほど生成した完全な Base64 文字列に設定します。
       # Example (Linux/macOS) - Use the actual string generated export CREDENTIALS_CONFIG="ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb..."

認証の優先順位と概要

サーバーは次の順序で資格情報を確認します。

1. CREDENTIALS_CONFIG (Base64コンテンツ)
2. SERVICE_ACCOUNT_PATH (サービス アカウント JSON へのパス)
3. CREDENTIALS_PATH (OAuth JSON へのパス) - トークンが見つからないか期限切れの場合に対話型フローをトリガーします。

環境変数の概要:

⚙️ サーバーの実行（詳細）

方法1： uvxを使用する（ユーザーに推奨）

ウルトラクイックスタートで紹介されているように、これが最も簡単な方法です。環境変数を設定して、次のコマンドを実行してください。

uvxパッケージの取得と実行を一時的に処理します。

方法2: 開発用（リポジトリのクローン作成）

コードを変更する場合:

1. クローン: git clone https://github.com/yourusername/mcp-google-sheets.git && cd mcp-google-sheets (実際の URL を使用)
2. **環境変数を設定します:**上記のとおりです。
3. uvを使用して実行: (ローカルコードを使用)
   uv run mcp-google-sheets # Or via the script name if defined in pyproject.toml, e.g.: # uv run start

🔌 Claude Desktop での使用

claude_desktop_config.jsonのmcpServersにサーバー設定を追加します。設定に一致するブロックを選択してください。

（初回使用時にはGoogleログイン用のブラウザが開く場合があります）

💬 クロードのプロンプト例

接続したら、次のようなプロンプトを試してください。

• 「アクセスできるすべてのスプレッドシートを一覧表示します。」（または「AI管理シートフォルダ内」）
• 「『2024年第3四半期の四半期売上レポート』というタイトルの新しいスプレッドシートを作成します。」
• 「「四半期売上レポート」スプレッドシートで、Sheet1 の範囲 A1 から E10 までのデータを取得します。」
• 「ID 1aBcDeFgHiJkLmNoPqRsTuVwXyZのスプレッドシートに「Summary」という名前の新しいシートを追加します。」
• 「「プロジェクト タスク」スプレッドシートの「タスク」シートで、セル B2 を「進行中」に更新します。」
• 「スプレッドシートXYZの「ログ」シートに次の行を追加します: [['2024-07-31', 'Task A Completed'], ['2024-08-01', 'Task B Started']] 」
• 「スプレッドシート「売上データ」と「在庫数」の概要を取得します。」
• 「「チームの休暇スケジュール」スプレッドシートを、 team@example.comを読者として、 manager@example.comを執筆者として共有します。通知は送信しません。」

🤝 貢献する

貢献を歓迎します！バグや機能リクエストについては、課題を開いて議論してください。プルリクエストも歓迎します。

📄 ライセンス

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

🙏 クレジット

• FastMCPで構築されました。
• kazz187/mcp-google-spreadsheetからインスピレーションを受けました。
• Google API Python クライアント ライブラリを使用します。