Spreadsheet Local MCP Server

Google Spreadsheet / Google Drive からデータを取得するための Local MCP (Model Context Protocol) サーバーです。 Stdio を使用して通信し、Claude Desktop などの MCP クライアントから直接利用できます。

機能

• データ取得: Google Spreadsheet や Google Drive 上の Excel ファイルからデータを読み込みます。
  • Google Sheets API と Drive API を併用し、Excel ファイルもサポートしています。

前提条件

• Node.js (v18以上推奨)
• Google Cloud Platform プロジェクト
  • Google Sheets API が有効化されていること
  • Google Drive API が有効化されていること
  • OAuth 2.0 クライアント ID が作成されていること

Google Cloud Credentials の取得方法

このサーバーを使用するには、Google Cloud Platform (GCP) でプロジェクトを作成し、OAuth 2.0 クライアント ID を取得する必要があります。

1. プロジェクトの作成と API の有効化

1. Google Cloud Console にアクセスします。
2. 新しいプロジェクトを作成します（または既存のプロジェクトを選択します）。
3. 左側のメニューから「API とサービス」>「ライブラリ」を選択します。
4. 以下の API を検索し、それぞれ「有効にする」をクリックします。
   • Google Sheets API
   • Google Drive API

2. OAuth 同意画面の設定

1. 左側のメニューから「API とサービス」>「OAuth 同意画面」を選択します。
2. User Type で「外部」を選択し、「作成」をクリックします（テスト目的の場合は「外部」で自分のアカウントのみを許可するのが一般的です）。
3. アプリ情報（アプリ名、ユーザーサポートメールなど）を入力し、「保存して次へ」をクリックします。
4. 「スコープ」は今回は特に設定しなくても動作しますが、必要に応じて追加してください。「保存して次へ」をクリックします。
5. 「テストユーザー」で「ADD USERS」をクリックし、自分の Google アカウント（メールアドレス）を追加します。これを行わないと、認証時にエラーになります。
6. 「保存して次へ」をクリックし、最後に「ダッシュボードに戻る」をクリックします。

3. OAuth クライアント ID の作成

1. 左側のメニューから「API とサービス」>「認証情報」を選択します。
2. 上部の「認証情報を作成」をクリックし、「OAuth クライアント ID」を選択します。
3. アプリケーションの種類で「ウェブ アプリケーション」を選択します。
4. 名前を適当に入力します（例: "Local MCP Server"）。
5. 承認済みのリダイレクト URI に以下の URL を追加します。
   • http://localhost:8080/auth/callback
6. 「作成」をクリックします。
7. 表示された クライアント ID と クライアント シークレット をコピーし、.env ファイルに設定します。

セットアップ

1. リポジトリのクローン

   git clone <repository-url>
   cd spreadsheet_local_mcp_server
   

2. 依存関係のインストール

   npm install
   

3. 環境変数の設定 .env.example をコピーして .env を作成し、必要な値を設定します。

   cp .env.example .env
   

   .env ファイルを編集:

   PORT=8080
   GOOGLE_REDIRECT_URI=http://localhost:8080/auth/callback
   

   注意: Google Cloud Console の OAuth 同意画面設定で、テストユーザーとして自分のメールアドレスを追加し、リダイレクト URI (http://localhost:8080/auth/callback) を許可済みリダイレクト URI に追加してください。

4. ビルド

   npm run build
   

MCP クライアントの設定 (Claude Desktop)

Claude Desktop で使用するには、claude_desktop_config.json (通常 ~/Library/Application Support/Claude/claude_desktop_config.json にあります) に以下を追加します。

{
  "mcpServers": {
    "spreadsheet-local": {
      "command": "node",
      "args": ["/absolute/path/to/spreadsheet_local_mcp_server/dist/index.js"],
      "env": {
        "GOOGLE_REDIRECT_URI": "http://localhost:8080/auth/callback"
      }
    }
  }
}

※ /absolute/path/to/... の部分は、実際にリポジトリをクローンした絶対パスに置き換えてください。

認証フロー

初回利用時やトークン期限切れ時は、認証が必要です。

以下のコマンドでサーバーを起動してください。

npm run dev
# または
npm run build
npm start

MCP サーバーが起動すると、認証が必要な場合に自動的にローカルサーバー (http://localhost:8080) が立ち上がり、ブラウザが開きます。 もし自動で開かない場合は、ブラウザで http://localhost:8080/auth/login にアクセスし、Google アカウントでログインして権限を許可してください。 認証が完了すると、MCP サーバーとしての機能が利用可能になります。

注意: すでに認証済み（.tokens.json が存在する）の場合、サーバーは MCP モード（Stdio）で起動し、コンソールには何も出力されず、Web サーバーも起動しません。これは正常な動作です。 再認証を行いたい場合は、.tokens.json を削除してからコマンドを実行してください。

利用可能なツール

get_data

Google Spreadsheet または Google Drive 上のファイルからデータを取得します。

• 引数:
  • url (string, 必須): Google Spreadsheet の URL または Google Drive のファイル URL
  • sheetName (string, オプション): シート名。省略時は最初のシートが使用されます。

ディレクトリ構成

• src/index.ts: エントリーポイント。認証サーバーの起動制御と MCP サーバーの初期化を行います。
• src/mcp.ts: MCP サーバーの設定 (Stdio) とツール定義 (get_data)。
• src/auth.ts: Google OAuth 認証ロジック。
• src/sheets.ts: Google Sheets API 操作ロジック。
• src/drive.ts: Google Drive API 操作ロジック。