README.md•4.51 kB
# Spreadsheet MCP Server
このプロジェクトは、Google SpreadsheetのデータにアクセスするためのModel Context Protocol (MCP) サーバーです。LLMがスプレッドシート情報を直接利用できるようにします。
## 機能
- スプレッドシートの基本情報（シート一覧など）の取得
- 特定シートのデータの取得とマークダウン形式での整形
- MCPクライアント（Claude for Desktopなど）と統合
## インストール
```bash
# リポジトリのクローン
git clone https://github.com/your-username/spreadsheet-mcp-server.git
cd spreadsheet-mcp-server
# 依存関係のインストール
npm install
# 環境変数の設定
cp .env.example .env
# .envファイルを編集してGAS_WEB_APP_URLとGAS_API_KEYを設定
# ビルド
npm run build
```
## 環境変数の設定
サーバーの設定には、以下の環境変数が使用されます：
- `GAS_WEB_APP_URL`: Google Apps Script Web AppのURL
- `GAS_API_KEY`: Google Apps Script Web Appのアクセス用APIキー
これらの環境変数は `.env` ファイルに設定できます：
```
GAS_WEB_APP_URL=https://script.google.com/macros/s/your-deployment-id/exec
GAS_API_KEY=your-api-key
```
環境変数が設定されていない場合、サーバーはモックモードで動作し、実際のGoogleスプレッドシートにはアクセスしません。
## 使用方法
### スタンドアロンでの起動
```bash
npm start
```
### Claude for Desktopとの統合
Claude for Desktopの設定ファイル (`claude_desktop_config.json`) に以下を追加します：
```json
{
"mcpServers": {
"spreadsheet": {
"command": "node",
"args": ["<absolute-path-to-project>/build/index.js"]
}
}
}
```
環境変数を設定するには、以下のように`env`フィールドを追加します：
```json
{
"mcpServers": {
"spreadsheet": {
"command": "node",
"args": ["<absolute-path-to-project>/build/index.js"],
"env": {
"GAS_WEB_APP_URL": "https://script.google.com/macros/s/your-deployment-id/exec",
"GAS_API_KEY": "your-api-key"
}
}
}
}
```
設定ファイルは以下の場所にあります：
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%AppData%\\Claude\\claude_desktop_config.json`
### MCP Inspectorでテスト
```bash
npx @modelcontextprotocol/inspector node build/index.js
```
## 提供するツール
### getSpreadsheet
スプレッドシートの基本情報と含まれるシート一覧を取得します。
**入力パラメータ**:
- `url`: スプレッドシートのURL
**出力**:
- スプレッドシート名、ID、シート一覧（行数・列数を含む）
### getSheetData
スプレッドシートの特定シートのデータを取得します。
**入力パラメータ**:
- `url`: スプレッドシートのURL
- `sheetName`: 取得するシート名
**出力**:
- シートデータ（マークダウンテーブル形式）
## 開発
### プロジェクト構造
```
src/
├── index.ts # エントリポイント
├── server.ts # MCPサーバー設定
├── config.ts # 環境変数と設定管理
├── tools/ # ツール実装
│ ├── getSpreadsheet.ts
│ ├── getSheetData.ts
│ └── index.ts
├── api/ # API処理
│ ├── README.md # API仕様
│ ├── spreadsheet.ts
│ └── types.ts
└── utils/ # ユーティリティ
└── format.ts
```
### テスト
```bash
# 単体テスト実行
npm test
# ウォッチモードでテスト
npm run test:watch
```
## Google Apps Scriptとの連携について
このサーバーは、実際の使用時にはGoogle Apps ScriptのWeb Appと連携して動作します：
1. Google Apps Scriptで[Web App](https://developers.google.com/apps-script/guides/web)を作成する
2. Webアプリ側でスプレッドシートにアクセスするAPIを実装する（`api/README.md`参照）
3. APIキーを設定し、環境変数`GAS_WEB_APP_URL`と`GAS_API_KEY`で連携する
このアプローチにより、Google認証フローを回避し、スプレッドシートのセキュリティを維持できます。
環境変数が設定されていない場合は、モックモードで動作し、テスト用のデータが返されます。
## ライセンス
MIT