Skip to main content
Glama

gsheets-mcp

Website License: MIT

Claude が Google Sheets API v4 を通じてあなたの Google Sheets を読み書きできるようにする、ローカル MCP(Model Context Protocol)サーバーです。

これは完全に自分のマシン上で動作します。認証は自分の Google アカウントで OAuth2(「インストール型アプリ」/ デスクトップフロー)を使って行い、あなたのデータが第三者サーバーを経由することは一切ありません。

MIT ライセンスの下で無料・オープンソースです。テレメトリはなく、第三者のサーバーも使用しません。

🌐 ウェブサイト: https://gsheets-mcp.trombella.org/

できること

ツール

機能

list_spreadsheets

Drive 上のあなたの Google Sheets を一覧表示します(名前でフィルタリング可能)。

get_sheet_info

スプレッドシートのメタデータ:タイトル、ロケール、タブ(名前、ID、サイズ)。

read_range

範囲(例:Foglio1!A1:D10)から値を読み取ります。

update_range

範囲に値を書き込む/上書きします。

append_rows

テーブルの末尾に行を追加します。

ほとんどのツールはスプレッドシート ID を受け取ります。これはシートの URL 内の長い文字列です: https://docs.google.com/spreadsheets/d/<THIS_IS_THE_ID>/edit。 ID は手でコピーする代わりに list_spreadsheets で見つけることもできます。


Related MCP server: sheetsdb-mcp-server

前提条件

  • Node.js 18+(node --version)。

  • Google アカウント。


パート1 — Google Cloud のセットアップ(1回だけ)

サーバーがシートへのアクセス許可を求めるために、OAuth「デスクトップ アプリ」クライアントが必要です。

1. Google Cloud プロジェクトを作成する

  1. https://console.cloud.google.com/ にアクセスします。

  2. 上部バー → プロジェクトのドロップダウン → 新しいプロジェクト。名前を付けて(例:gsheets-mcp)作成します。選択されていることを確認します。

2. API を有効にする

  1. API とサービス → ライブラリ に移動します(https://console.cloud.google.com/apis/library)。

  2. Google Sheets API を検索して開き、有効にする をクリックします。

  3. Google Drive API を検索して開き、有効にする をクリックします。

Drive API は、読み取り専用の drive.readonly スコープを介して、list_spreadsheets がシートを列挙するためだけに使用されます。ファイルの変更、移動、削除には使用されません。

3. OAuth 同意画面を設定する

  1. API とサービス → OAuth 同意画面 に移動します。

  2. ユーザーの種類: 外部 → 作成 をクリックします。(内部 は Google Workspace 組織でのみ利用可能です。)

  3. 必須フィールドを入力します:アプリ名(例:gsheets-mcp)、メールアドレスを ユーザーサポートメール と デベロッパーの連絡先 に入力します。残りは空白でも構いません。保存して次へ をクリックします。

  4. スコープ: ここではスコープの追加を省略できます(アプリはログイン時に要求します)。保存して次へ をクリックします。

  5. テストユーザー: ユーザーを追加 をクリックし、自分の Google メールアドレス を追加します。これは必須です —「テスト」モードでは、一覧に登録されたテストユーザーのみがアプリを承認できます。保存して次へ をクリックします。

  6. アプリはテストモードのままにします。個人利用にはこれで問題なく、自分のテストユーザーアカウントでは期限切れになりません。(「本番環境」に公開すると Google のアプリ審査が発生しますが、ここでは不要です。)

4. OAuth クライアントの認証情報を作成する

  1. API とサービス → 認証情報 に移動します。

  2. 認証情報を作成 → OAuth クライアント ID を選択します。

  3. アプリケーションの種類: デスクトップ アプリ。名前を付けます(例:gsheets-mcp desktop)。作成 をクリックします。

  4. 確認ダイアログで JSON をダウンロード をクリックします。このファイルには client_id と client_secret が含まれています。

5. 認証情報ファイルを配置する

ダウンロードしたファイルを credentials.json として設定ディレクトリに保存します:

mkdir -p ~/.config/gsheets-mcp
mv ~/Downloads/client_secret_*.json ~/.config/gsheets-mcp/credentials.json

このファイルは非公開にしてください — git では無視されます。場所は GSHEETS_MCP_CREDENTIALS 環境変数で上書きできます(.env.example を参照)。


パート2 — インストールとビルド

プロジェクトフォルダから:

npm install
npm run build

パート3 — ログイン(1回だけ)

対話型ログインを実行します。ブラウザで Google の同意画面が開くので、アクセスを承認すると、トークンが ~/.config/gsheets-mcp/token.json に保存されます(以後は自動的に更新されます)。

npm run login
# equivalently: node dist/index.js login

アプリがテストモードのため、Google は 「Google はこのアプリを確認していません」 という警告を表示します。これは自分のアプリでは想定どおりです — 詳細 → gsheets-mcp(安全でない)に移動 をクリックして続行します。次に、要求された 2 つの権限を付与します(下記参照)。

ターミナルに ✅ Authorization complete と表示されたら完了です。

要求されるスコープ:

  • https://www.googleapis.com/auth/spreadsheets — スプレッドシートへの読み書き。

  • https://www.googleapis.com/auth/drive.readonly — 読み取り専用。list_spreadsheets がシートを列挙するためだけに使用されます。ファイルの変更や削除はできません。

いつでもアクセスを無効にするには、https://myaccount.google.com/permissions にアクセスします。

注意: サーバーをアップグレードして要求されるスコープが変わった場合は、npm run login を再度実行する必要があります — 以前に付与した同意は新しいスコープをカバーしません。同じことがマシンごとに当てはまります(各コンピュータが独自のトークンを保存します)。


パート4 — Claude Desktop にサーバーを追加する

Claude Desktop の設定ファイルを開きます:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

mcpServers の下に gsheets エントリを追加し、コンパイル済みのエントリポイントを指定します。このプロジェクトの dist/index.js への絶対パスを使用します:

{
  "mcpServers": {
    "gsheets": {
      "command": "node",
      "args": ["/absolute/path/to/google-sheets-mcp/dist/index.js"]
    }
  }
}

ファイルを保存し、Claude Desktop を完全に終了してから開き直します。すると gsheets ツールが利用可能になっているはずです。次のように Claude に試しに頼んでみてください:

「Google Sheets を一覧表示して、'Budget' という名前のシートから A1:C5 を読み取って。」

Claude Code で使う

claude mcp add gsheets -- node /absolute/path/to/google-sheets-mcp/dist/index.js

使用例(Claude に頼む内容)

  • 一覧: 「Google Sheets を一覧表示して」/ 「名前に 'budget' を含むスプレッドシートを探して。」

  • 情報: 「スプレッドシート <ID> にはどのタブがありますか?」(使用する正確なタブ名が返されます)。

  • 読み取り: 「スプレッドシート <ID> の範囲 Foglio1!A1:D10 を読み取って。」

  • 更新: 「スプレッドシート <ID> の Foglio1!A1 を起点に、値 [["Name","Score"],["Ada",42]] を入れて。」

  • 追記: 「スプレッドシート <ID> の Foglio1 に行 ["Grace", 99] を追加して。」

⚠️ 注意: タブ名はローカライズされています

範囲にはタブ(シート)名を使用します(例:Sheet1!A1:D10)。ただし、デフォルトのタブ名は Google アカウントの言語によって異なります。英語では Sheet1、イタリア語では Foglio1、スペイン語では Hoja1、フランス語では Feuille1 などです。間違った名前を使用すると Unable to parse range: … が返されます。

実際のタブ名が分からない場合は、シートを開いて下部のタブのラベルを確認するか、範囲としてタブ名のみを渡して(例:Foglio1)シート全体を読み取るよう Claude に頼んでください。正確なタブ名を一覧表示する専用の get_sheet_info ツールはロードマップに含まれています。

設定リファレンス

すべてオプションです。デフォルトですぐに動作します。.env.example を参照してください。

変数

デフォルト

目的

GSHEETS_MCP_CONFIG_DIR

~/.config/gsheets-mcp

credentials.json / token.json が置かれる場所。

GSHEETS_MCP_CREDENTIALS

<config dir>/credentials.json

OAuth クライアントファイルへのパス。

GSHEETS_MCP_TOKEN

<config dir>/token.json

保存されたトークンへのパス。

ヘッドレス / HTTP モード(下記参照)では、代わりに環境変数で認証情報を提供できます:

変数

目的

GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET

credentials.json の代わりとなる OAuth クライアント。

GOOGLE_REFRESH_TOKEN

token.json の代わりとなる更新トークン(ブラウザでのログインは不要)。

MCP_AUTH_TOKEN

HTTP モードでは必須。クライアントが送信する必要がある Bearer トークン。

PORT

HTTP ポート(デフォルト 8000)。


リモート / モバイルでの使用(上級)

デフォルトのトランスポートは stdio(ローカル)です。このサーバーは HTTP 経由のリモート MCP コネクタとしても実行でき、ローカルプロセスを起動できないクライアント(例:Claude モバイルアプリ)からアクセスできます:

MCP_AUTH_TOKEN=$(openssl rand -hex 32) npm run serve:http   # listens on :8000/mcp

すべてのリクエストで Authorization: Bearer <MCP_AUTH_TOKEN> を送信する必要があります。このエンドポイントはスプレッドシートを書き込めるため、Bearer トークンに加えて必ずネットワークゲート(Cloudflare Access、VPN)の背後に置いてください — インターネットに直接公開しないでください。

個人用の常時稼働セットアップ(Cloudflare Tunnel の背後)向けの既製の Home Assistant OS アドオン は ha-addon/gsheets-mcp/ にあります。詳細な手順は DOCS.md を参照してください。


トラブルシューティング

  • 「Not authenticated. Run the one-time login first」 — まだログインしていないか、トークンファイルがありません。npm run login を実行してください。

  • 「OAuth client credentials not found」 — credentials.json がサーバーの期待する場所にありません。パート1の手順5を確認してください。

  • 403 access_denied がブラウザに表示される — Google アカウントがテストユーザーとして登録されていません。OAuth 同意画面 → テストユーザー(パート1、手順3.5)で追加してください。

  • 「Request had insufficient authentication scopes」 — 保存されたトークンがスコープ変更前のものです(例:list_spreadsheets には drive.readonly が必要)。再同意のため npm run login を再度実行してください。

  • Unable to parse range: … — タブ名が間違っています。タブ名はローカライズされます(イタリア語では Foglio1、英語では Sheet1)。正確な名前を確認するには get_sheet_info を使用してください。

  • refresh_token がないという警告 — https://myaccount.google.com/permissions でアプリを取り消し、npm run login を再度実行してください。

  • Claude Desktop にツールが表示されない — claude_desktop_config.json のパスが絶対パスで dist/index.js を指していること、npm run build を実行したこと、Claude Desktop を完全に再起動したことを確認してください。


開発

npm run build       # compile to dist/
npm run watch       # recompile on change
npm run typecheck   # type-check without emitting

ソースの構成: src/index.ts(エントリポイント)、src/auth.ts(OAuth)、src/sheetsClient.ts と src/driveClient.ts(API ラッパー)、src/tools/*(MCP ツールごとに1ファイル)。


ライセンス

MIT ライセンス の下で公開されています。自由に使用、変更、配布できます。もし時間の節約になったなら、コーヒー一杯で開発を支援できます — リンクはウェブサイトにあります。☕

Google との提携や承認はありません。「Google Sheets」は Google LLC の商標です。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers