Spreadsheet MCP Server

An MCP server for Google Spreadsheet integration, connecting via a Google Apps Script Web App.

GitHub

Spreadsheet MCP Server

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

機能

  • スプレッドシートの基本情報（シート一覧など）の取得
  • 特定シートのデータの取得とマークダウン形式での整形
  • MCPクライアント（Claude for Desktopなど）と統合

インストール

# リポジトリのクローン
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スプレッドシートにはアクセスしません。

使用方法

スタンドアロンでの起動

npm start

Claude for Desktopとの統合

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

{
  "mcpServers": {
    "spreadsheet": {
      "command": "node",
      "args": ["<absolute-path-to-project>/build/index.js"]
    }
  }
}

環境変数を設定するには、以下のようにenvフィールドを追加します：

{
  "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でテスト

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

テスト

# 単体テスト実行
npm test

# ウォッチモードでテスト
npm run test:watch

Google Apps Scriptとの連携について

このサーバーは、実際の使用時にはGoogle Apps ScriptのWeb Appと連携して動作します：

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

このアプローチにより、Google認証フローを回避し、スプレッドシートのセキュリティを維持できます。

環境変数が設定されていない場合は、モックモードで動作し、テスト用のデータが返されます。

ライセンス

MIT

Servidores relacionados