MCP Google Sheets Server

MCP Google Sheets サーバー

Google Sheets API と連携する Model Context Protocol（MCP）サーバーです。MCP クライアント（Claude Code、Claude Desktop、Cursor など）から Google Sheets ドキュメントを直接読み取り、書き込み、管理できます。

主な機能

• Google Sheets との完全な連携：スプレッドシートの読み取り、書き込み、管理
• 高度な操作：一括操作、書式設定、グラフ、条件付き書式設定
• 柔軟な認証：ファイル形式と JSON 文字列形式の認証情報に対応
• 本番環境に対応：TypeScript で構築され、包括的なエラー処理と完全なテストカバレッジを備えています

必要条件

• Node.js v22 以降
• Sheets API が有効になっている Google Cloud プロジェクト
• JSON キーファイルを含むサービスアカウント
• npm

はじめに

クイックインストール（推奨）

以下の設定を MCP クライアントに追加します。

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "npx",
      "args": ["-y", "mcp-gsheets@latest"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
      }
    }
  }
}

メモ

mcp-gsheets@latest を使用すると、MCP クライアントで MCP Google Sheets サーバーの最新バージョンを常に使用できます。

MCP クライアントの設定

claude mcp add mcp-gsheets npx mcp-gsheets@latest

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "npx",
      "args": ["mcp-gsheets@latest"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "npx",
      "args": ["-y", "mcp-gsheets@latest"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
      }
    }
  }
}

Google Cloud のセットアップ

1. Google Cloud Console にアクセスします
2. 新しいプロジェクトを作成するか、既存のプロジェクトを選択します
3. Google Sheets API を有効にします。
   • 「APIs & Services」→「Library」に移動します
   • 「Google Sheets API」を検索し、「Enable」をクリックします
4. サービスアカウントを作成します。
   • 「APIs & Services」→「Credentials」に移動します
   • 「Create Credentials」→「Service Account」をクリックします
   • サービスアカウントの一覧で、Actions 列の三点リーダーをクリックし、Manage keys → Add key → Create new key の順に選択して、JSON 形式を選択します
   • JSON キーファイルをダウンロードします
5. スプレッドシートを共有します。
   • Google Sheets を開きます
   • 「Share」をクリックし、サービスアカウントのメールアドレス（JSON ファイル内に記載）を追加します
   • 「Editor」権限を付与します

代替の認証方法

オプション 1：JSON 文字列による認証

認証情報にファイルパスを使う代わりに、サービスアカウントの認証情報を JSON 文字列として直接指定できます。コンテナ化された環境や CI/CD パイプラインでの使用、または認証情報ファイルの管理を避けたい場合に便利です。

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "npx",
      "args": ["-y", "mcp-gsheets@latest"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_SERVICE_ACCOUNT_KEY": "{\"type\":\"service_account\",\"project_id\":\"your-project\",\"private_key_id\":\"...\",\"private_key\":\"-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n\",\"client_email\":\"[email protected]\",\"client_id\":\"...\",\"auth_uri\":\"https://accounts.google.com/o/oauth2/auth\",\"token_uri\":\"https://oauth2.googleapis.com/token\",\"auth_provider_x509_cert_url\":\"https://www.googleapis.com/oauth2/v1/certs\",\"client_x509_cert_url\":\"...\"}"
      }
    }
  }
}

注記：GOOGLE_SERVICE_ACCOUNT_KEY を使用する場合：

• JSON 全体を 1 行に収める必要があります
• すべての引用符をバックスラッシュでエスケープする必要があります
• 秘密鍵の改行は \\n として表す必要があります
• JSON に project_id が含まれている場合、GOOGLE_PROJECT_ID は省略できます

オプション 2：秘密鍵による認証（簡易版）

最も使いやすい方法として、秘密鍵とメールアドレスだけを直接指定できます。最もシンプルな方法で、サービスアカウントの JSON に含まれる 2 つのフィールドだけが必要です。

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "npx",
      "args": ["-y", "mcp-gsheets@latest"],
      "env": {
        "GOOGLE_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCgR6bvMNOUHZ29\\n+YgbVHAXsT/s+L/jnXTCB193zikCzspSBSfxLu8VRDjkNq9WUoDxizTATzMFNvNf\\n...\\n-----END PRIVATE KEY-----\\n",
        "GOOGLE_CLIENT_EMAIL": "[email protected]"
      }
    }
  }
}

注記：GOOGLE_PRIVATE_KEY を使用する場合：

• 秘密鍵の改行は \\n として表します
• 秘密鍵には -----BEGIN PRIVATE KEY----- と -----END PRIVATE KEY----- のマーカーを含める必要があります
• クライアントのメールアドレスには、JSON ファイルに記載されたサービスアカウントのメールアドレスを指定してください
• この方法では GOOGLE_PROJECT_ID は省略可能です

ローカル開発環境のセットアップ

このプロジェクトの開発やコントリビュートを行う場合は、ローカルにクローンしてビルドできます。

# Clone the repository
git clone https://github.com/freema/mcp-gsheets.git
cd mcp-gsheets

# Install dependencies
npm install

# Build the project
npm run build

対話式セットアップスクリプト

対話式セットアップスクリプトを実行して、ローカルの MCP クライアントを設定します。

npm run setup

このスクリプトでは、以下を行います。

• 設定手順を案内します
• nvm を含め、Node.js のインストールを自動的に検出します
• Claude Desktop の設定を検索します
• 適切な JSON 設定を作成します
• 開発用の .env ファイルを任意で作成します

ローカルでの手動設定

ローカルビルドを使って手動で設定する場合は、MCP クライアントの設定に以下を追加します。

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-gsheets/dist/index.js"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
      }
    }
  }
}

📦 ビルドと開発

開発用コマンド

# Development mode with hot reload
npm run dev

# Build for production
npm run build

# Type checking
npm run typecheck

# Clean build artifacts
npm run clean

# Run MCP inspector for debugging
npm run inspector

# Run MCP inspector in development mode
npm run inspector:dev

タスクランナー（代替方法）

Task がインストールされている場合：

# Install dependencies
task install

# Build the project
task build

# Run in development mode
task dev

# Run linter
task lint

# Format code
task fmt

# Run all checks
task check

開発環境のセットアップ

1. テスト用の .env ファイルを作成します。

cp .env.example .env
# Edit .env with your credentials:
# GOOGLE_PROJECT_ID=your-project-id
# GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
# TEST_SPREADSHEET_ID=your-test-spreadsheet-id

2. 開発モードで実行します。

npm run dev  # Watch mode with auto-reload

🎚️ ツールセットでコンテキストコストを削減する

44 個すべてのツールを使用すると、モデルが何かを行う前に、各セッションで約 9,900 トークンのコンテキストを消費します。 多くのワークフローで必要なのは、その一部だけです。 GSHEETS_TOOLSETS を使うと、サーバーが公開するツールを制限できます。

{
  "mcpServers": {
    "gsheets": {
      "command": "npx",
      "args": ["mcp-gsheets"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/key.json",
        "GSHEETS_TOOLSETS": "core,charts"
      }
    }
  }
}

測定された tools/list のコスト：

注記：

• デフォルトの動作は変わりません — GSHEETS_TOOLSETS を未設定のままにすると、これまでどおりすべてのツールが使用されます。
• core は常に含まれます。 GSHEETS_TOOLSETS=charts は「core に加えて charts」を意味し、「charts のみ」ではありません。core がなければ、サーバーはセルを読み取れません。
• 入力ミスは起動エラーになります。ツール一覧が通知なく縮小されることはありません。
• GSHEETS_READ_ONLY=true を指定すると、書き込みツールがすべて除外されます。また、GSHEETS_TOOLSETS と組み合わせることもできます。この設定は一覧の作成時だけでなく、ツールの呼び出し時にも適用されるため、クライアントが非表示のツールを指定して書き込むことはできません。

すべてのツールには MCP アノテーション（readOnlyHint、destructiveHint、idempotentHint）も付与されるため、クライアントは読み取り時の確認プロンプトを省略し、破壊的な操作の前に警告できます。

📋 利用可能なツール

データの読み取り

データの書き込み

シートの管理

セルの書式設定

ネイティブテーブル

グラフ

読み取り／スナップショットツール

🔧 コード品質

リント

# Run ESLint
npm run lint

# Fix auto-fixable issues
npm run lint:fix

フォーマット

# Check formatting with Prettier
npm run format:check

# Format code
npm run format

型チェック

# Run TypeScript type checking
npm run typecheck

❗ トラブルシューティング

よくある問題

「Authentication failed」

• ファイルベースの認証を使用している場合：JSON キーのパスが絶対パスで正しいことを確認してください
• JSON 文字列による認証を使用している場合：JSON が適切にエスケープされ、有効であることを確認してください
• 秘密鍵認証を使用している場合：秘密鍵に BEGIN/END マーカーが含まれ、改行が \\n としてエスケープされていることを確認してください
• GOOGLE_CLIENT_EMAIL が有効なサービスアカウントのメールアドレスであることを確認してください
• GOOGLE_PROJECT_ID がプロジェクトと一致していることを確認してください（または、完全な JSON 認証を使用する場合は JSON に含まれていることを確認してください）
• Sheets API が有効になっていることを確認してください

「Permission denied」

• スプレッドシートをサービスアカウントのメールアドレスと共有してください
• サービスアカウントには「Editor」ロールが必要です
• JSON ファイル内のメールアドレス（client_email フィールド）を確認してください

「Spreadsheet not found」

• URL からスプレッドシート ID を確認してください
• 形式：https://docs.google.com/spreadsheets/d/[SPREADSHEET_ID]/edit

MCP 接続の問題

• ビルド済みのバージョン（dist/index.js）を使用していることを確認してください
• Claude Desktop の設定で Node.js のパスが正しいことを確認してください
• Claude Desktop のログでエラーを確認してください
• npm run inspector を使用してデバッグしてください

🔍 ID の確認

スプレッドシート ID

URL から確認します：

https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit
                                        ↑ This is the spreadsheet ID

シート ID

sheets_get_metadata を使用して、すべてのシートとその ID を一覧表示します。

📝 ヒント

1. 必ずデータのコピーでテストしてください
2. パフォーマンスを向上させるには、バッチ操作を使用してください
3. 適切な権限（読み取り専用または編集）を設定してください
4. 大規模な操作ではレート制限を確認してください
5. 操作前に sheets_check_access を使用して権限を確認してください

📘 ツールの詳細

sheets_get_sheet_structure

セルごとのデータを含めずに、シートの軽量な構造・寸法メタデータを返します。レイアウト情報だけが必要な場合は、sheets_get_full_sheet_snapshot よりもはるかに高速で、コストも低くなります。

パラメーター：

• spreadsheetId（必須）：スプレッドシートの ID
• sheetName（必須）：シート（タブ）の名前

戻り値： sheetName、sheetId、sheetIndex、tabColor、tabColorStyle、dimensions（rowCount、columnCount）、frozen（rowCount、columnCount）、columnWidths（ピクセルサイズの配列）、rowHeights（ピクセルサイズの配列）、hiddenColumns（0 始まりのインデックス）、hiddenRows（0 始まりのインデックス）、mergeCount、merges（A1 表記の配列）

sheets_get_formatting_compact

範囲のセル書式を読み取り、コンパクトな A1Range → 書式のペアとして返します。書式が同一の隣接セルは矩形範囲にまとめられ、ランレングスエンコードされるため、セルごとのデータと比べて出力を 90％以上削減できます。

パラメーター：

• spreadsheetId（必須）：スプレッドシートの ID
• sheetName（必須）：シート（タブ）の名前
• range（必須）：シート接頭辞を含まない範囲。例："A1:Z85"
• useEffectiveFormat（任意）：false（デフォルト）= userEnteredFormat（明示的な上書きのみ。出力が小さくなります）；true = effectiveFormat（継承されたデフォルトをすべて含みます）
• fields（任意）：含める書式フィールド名の配列。例：["backgroundColor", "textFormat", "borders"]

戻り値： { range, formatType, rangeCount, data: { "A1:C3": { backgroundColor: {...} }, ... } }

対応フィールド： backgroundColor、backgroundColorStyle、textFormat、horizontalAlignment、verticalAlignment、wrapStrategy、textRotation、numberFormat、padding、borders

sheets_get_full_sheet_snapshot

1 回の API 呼び出しで、すべての構造および書式メタデータを返すマスター一括取得ツールです。

パラメーター：

• spreadsheetId（必須）：スプレッドシートの ID
• sheetName（必須）：シート（タブ）の名前
• includeFormattingRange（任意）：指定すると（例："A1:Z100"）、セルごとの書式がレスポンスに含まれます
• useEffectiveFormat（任意）：セルの書式を含める際に、userEnteredFormat の代わりに effectiveFormat を使用します（デフォルト：false）
• fields（任意）：返す書式フィールド名の配列です。例：["backgroundColor", "textFormat"]。API の転送サイズとレスポンスサイズを削減します
• compactMode（任意）：true の場合、隣接する同一セルを矩形範囲にまとめます（RLE）。一般的な 85×28 のシートを約 60 000 行から約 500 行に削減します（デフォルト：false）

sheets_insert_rows

オプションでデータを指定して、スプレッドシートの特定の位置に新しい行を挿入します。

パラメーター：

• spreadsheetId（必須）：スプレッドシートの ID
• range（必須）：行を挿入する位置を示す A1 表記のアンカーポイント（例："Sheet1!A5"）
• rows（任意）：挿入する行数（デフォルト：1）
• position（任意）：アンカー行の「BEFORE」または「AFTER」（デフォルト：「BEFORE」）
• inheritFromBefore（任意）：直前の行から書式を引き継ぐかどうか（デフォルト：false）
• values（任意）：挿入した行に入力する値の 2 次元配列
• valueInputOption（任意）：「RAW」または「USER_ENTERED」（デフォルト：「USER_ENTERED」）

例：

// Insert 1 empty row before row 5
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "Sheet1!A5"
}

// Insert 3 rows after row 10 with data
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "Sheet1!A10",
  "rows": 3,
  "position": "AFTER",
  "values": [
    ["John", "Doe", "[email protected]"],
    ["Jane", "Smith", "[email protected]"],
    ["Bob", "Johnson", "[email protected]"]
  ]
}

sheets_delete_columns

列全体を指定する A1 範囲を使用して、シートから 1 列以上を削除します。

パラメーター：

• spreadsheetId（必須）：スプレッドシートの ID
• range（必須）：削除する列全体を指定する A1 範囲（例："Sheet1!B:D" または "Sheet1!C:C"）

例：

// Delete columns B through D from Sheet1
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "Sheet1!B:D"
}

// Delete a single column from the first sheet
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "C:C"
}

sheets_delete_rows

行全体を指定する A1 範囲を使用して、シートから 1 行以上を削除します。

パラメーター：

• spreadsheetId（必須）：スプレッドシートの ID
• range（必須）：削除する行全体を指定する A1 範囲（例："Sheet1!2:4" または "Sheet1!3:3"）

例：

// Delete rows 2 through 4 from Sheet1
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "Sheet1!2:4"
}

// Delete a single row from the first sheet
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "3:3"
}

📋 変更履歴

各バージョンの変更一覧は、CHANGELOG.md をご覧ください。

🤝 貢献

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. テストとリンティングを実行します（npm run check）
4. 変更をコミットします（git commit -m 'Add some amazing feature'）
5. ブランチにプッシュします（git push origin feature/amazing-feature）
6. プルリクエストを作成します

👤 作者

Tomáš Grásl - tomasgrasl.cz

📄 ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細は LICENSE ファイルをご覧ください。