gsheets-mcp

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

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

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

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

できること

ほとんどのツールはスプレッドシート 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 を参照してください。

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

リモート / モバイルでの使用（上級）

デフォルトのトランスポートは 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 の商標です。