Hosakakeigo Spreadsheet MCP Server

🚀 Google スプレッドシート MCP サーバー

このプロジェクトは、Google スプレッドシートのデータにアクセスするための Model Context Protocol (MCP) サーバーです。LLM が直接スプレッドシートの情報を利用できるようにします。

✨ 主な機能

• スプレッドシートの基本情報（ワークシートリストなど）を取得する
• 特定のワークシートのデータを取得し、Markdown 形式で整理する
• MCP クライアント（Desktop 版 Claude など）と統合する

📦 インストール

# リポジトリをクローンする
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 スクリプト Web アプリの URL
• GAS_API_KEY: Google Apps スクリプト Web アプリにアクセスするための API キー

これらの環境変数は .env ファイルで設定できます：

GAS_WEB_APP_URL=https://script.google.com/macros/s/your-deployment-id/exec
GAS_API_KEY=your-api-key

環境変数が設定されていない場合、サーバーは模擬モードで実行され、実際に Google スプレッドシートにアクセスすることはありません。

使用方法

単独で起動する

npm start

Desktop 版 Claude と統合する

Desktop 版 Claude の設定ファイル (claude_desktop_config.json) に以下の内容を追加します：

{
  "mcpServers": {
    "spreadsheet": {
      "command": "node",
      "args": ["<プロジェクトの絶対パス>/build/index.js"]
    }
  }
}

環境変数を設定するには、設定ファイルに env フィールドを追加します：

{
  "mcpServers": {
    "spreadsheet": {
      "command": "node",
      "args": ["<プロジェクトの絶対パス>/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 サーバーの使用

スプレッドシートのデータにアクセスするには、コード内で MCP サービスを呼び出します：

import { createMCPClient } from 'mcp-client'

const mcp = await createMCPClient('spreadsheet')
await mcp.query('スプレッドシートの内容を取得する', {
  spreadsheetId: '<スプレッドシート ID>',
  sheetName: '<ワークシート名>'
})

開発情報

プロジェクト構造

プロジェクトのフォルダ構造は以下の通りです：

src/
  |- api/                   # Web アプリとのやり取りを定義するインターフェース
  |- mock/                 # 環境変数が設定されていない場合に使用する模擬データ
  |- services/             # スプレッドシートのデータを処理するコアロジック
    |- SpreadsheetService.ts   # スプレッドシートのデータを処理するクラス

開発手順

1. 依存関係をインストールする：

npm install

2. 開発サーバーを起動する：

npm run dev

テストの実行

テストを実行するには：

npm test

Google Apps スクリプト Web アプリの統合

Google スプレッドシートのデータを使用するには、以下の手順に従います：

1. Google Apps スクリプト Web アプリを作成する：作成ガイド
2. Web アプリでスプレッドシートにアクセスする API を実装する（api/README.md を参照）
3. 環境変数 GAS_WEB_APP_URL と GAS_API_KEY を設定する

この方法により、Google の認証を経ることなく、安全にスプレッドシートのデータを使用できます。 環境変数が設定されていない場合、サーバーは模擬モードで実行され、テストデータを返します。