What is Spreadsheet Mcp Server

The spreadsheet-mcp-server is a Model Context Protocol (MCP) server that allows access to data from Google Spreadsheets, enabling Large Language Models (LLMs) to utilize spreadsheet information directly.

Use cases

Use cases include generating reports from spreadsheet data, automating data retrieval for applications, and enhancing LLM capabilities by providing them with structured data from spreadsheets.

How to use

To use the spreadsheet-mcp-server, clone the repository, install dependencies, set up environment variables for Google Apps Script, build the project, and start the server. It can also be integrated with clients like Claude for Desktop by modifying the configuration file.

Key features

Key features include retrieving basic spreadsheet information (like sheet lists), fetching specific sheet data formatted in Markdown, and integration with MCP clients such as Claude for Desktop.

Where to use

The spreadsheet-mcp-server can be used in various fields such as data analysis, reporting, and automation tasks where Google Sheets are utilized for data management.

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