MCP Gsheets

🚀 MCP Google Sheets Server

Google Sheets APIを統合するためのModel Context Protocol (MCP)サーバーです。MCPクライアント（例：Claude Desktop）から直接Google Sheetsドキュメントの読み取り、書き込み、管理を行うことができます。

🚀 クイックスタート

1. 前提条件

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

2. インストール

# リポジトリをクローンする
git clone https://github.com/freema/mcp-gsheets.git
# またはSSHを使用する場合
# git clone git@github.com:freema/mcp-gsheets.git
cd mcp-gsheets

# 依存関係をインストールする
npm install

# プロジェクトをビルドする
npm run build

3. 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」をクリックします。
   • JSONキーファイルをダウンロードします。
5. スプレッドシートを共有します。
   • Googleスプレッドシートを開きます。
   • 「共有」をクリックし、サービスアカウントのメールアドレス（JSONファイルから）を追加します。
   • 「編集者」権限を付与します。

4. MCPクライアントの設定

簡単な設定（推奨）

対話型の設定スクリプトを実行します。

npm run setup

これにより、以下のことが行われます。

• 設定手順を案内します。
• Node.jsのインストールを自動的に検出します（nvmを含む）。
• Claude Desktopの設定を見つけます。
• 適切なJSON設定を作成します。
• 開発用に.envファイルをオプションで作成します。

手動設定

手動で設定する場合は、Claude Desktopの設定に追加します。

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

{
  "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"
      }
    }
  }
}

設定を追加した後、Claude Desktopを再起動します。

📦 ビルドと開発

開発コマンド

# ホットリロードを使用した開発モード
npm run dev

# 本番用にビルドする
npm run build

# 型チェック
npm run typecheck

# ビルドアーティファクトをクリーンアップする
npm run clean

# デバッグ用にMCPインスペクターを実行する
npm run inspector

# 開発モードでMCPインスペクターを実行する
npm run inspector:dev

タスクランナー（代替手段）

Taskをインストールしている場合は、以下のコマンドを使用できます。

# 依存関係をインストールする
task install

# プロジェクトをビルドする
task build

# 開発モードで実行する
task dev

# リンターを実行する
task lint

# コードをフォーマットする
task fmt

# すべてのチェックを実行する
task check

開発環境の設定

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

cp .env.example .env
# .envを編集して、あなたの資格情報を設定します。
# 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  # 自動リロードを使用したウォッチモード

📋 利用可能なツール

データの読み取り

• sheets_get_values - 範囲からデータを読み取ります。
• sheets_batch_get_values - 複数の範囲からデータを読み取ります。
• sheets_get_metadata - スプレッドシートの情報を取得します。
• sheets_check_access - アクセス権限を確認します。

データの書き込み

• sheets_update_values - 範囲にデータを書き込みます。
• sheets_batch_update_values - 複数の範囲にデータを書き込みます。
• sheets_append_values - テーブルに行を追加します。
• sheets_clear_values - セルの内容をクリアします。

シートの管理

• sheets_insert_sheet - 新しいシートを追加します。
• sheets_delete_sheet - シートを削除します。
• sheets_duplicate_sheet - シートをコピーします。
• sheets_copy_to - 別のスプレッドシートにコピーします。
• sheets_update_sheet_properties - シートの設定を更新します。

セルの書式設定

• sheets_format_cells - セルの書式を設定します（色、フォント、配置、数値形式）。
• sheets_update_borders - セルの境界線を追加または変更します。
• sheets_merge_cells - セルを結合します。
• sheets_unmerge_cells - 結合されたセルを解除します。
• sheets_add_conditional_formatting - 条件付き書式ルールを追加します。

🔧 コード品質

リンティング

# ESLintを実行する
npm run lint

# 自動修正可能な問題を修正する
npm run lint:fix

フォーマット

# Prettierでフォーマットをチェックする
npm run format:check

# コードをフォーマットする
npm run format

型チェック

# TypeScriptの型チェックを実行する
npm run typecheck

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

一般的な問題

「Authentication failed」

• JSONキーのパスが絶対パスで正しいことを確認します。
• GOOGLE_PROJECT_IDがあなたのプロジェクトと一致することを確認します。
• Sheets APIが有効になっていることを確認します。

「Permission denied」

• スプレッドシートをサービスアカウントのメールアドレスで共有します。
• サービスアカウントに「編集者」ロールが必要です。
• 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
                                        ↑ これがスプレッドシートIDです

シートID

sheets_get_metadataを使用して、すべてのシートとそのIDをリストアップできます。

📝 ヒント

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

🤝 コントリビュート

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. プルリクエストを作成します。

📄 ライセンス

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