# 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](https://console.cloud.google.com/) にアクセスします。
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. **リポジトリのクローン**
   ```bash
   git clone <repository-url>
   cd spreadsheet_local_mcp_server
   ```

2. **依存関係のインストール**
   ```bash
   npm install
   ```

3. **環境変数の設定**
   `.env.example` をコピーして `.env` を作成し、必要な値を設定します。
   ```bash
   cp .env.example .env
   ```
   
   `.env` ファイルを編集:
   ```env
   PORT=8080
   GOOGLE_REDIRECT_URI=http://localhost:8080/auth/callback
   ```
   
   > **注意**: Google Cloud Console の OAuth 同意画面設定で、テストユーザーとして自分のメールアドレスを追加し、リダイレクト URI (`http://localhost:8080/auth/callback`) を許可済みリダイレクト URI に追加してください。

4. **ビルド**
   ```bash
   npm run build
   ```

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

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

```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/...` の部分は、実際にリポジトリをクローンした絶対パスに置き換えてください。

## 認証フロー

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

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

```bash
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 操作ロジック。