Spreadsheet MCP Server

This project is a Model Context Protocol (MCP) server for accessing data from Google Spreadsheets, making the spreadsheet information directly available to LLM.

function

• Acquiring basic information about a spreadsheet (such as a list of sheets)

• Get data from a specific sheet and format it in Markdown format

• Integrates with MCP clients (e.g. Claude for Desktop)

Related MCP server: MCP Google Workspace Server

install

# リポジトリのクローン
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

Setting environment variables

The following environment variables are used to configure the server:

• GAS_WEB_APP_URL : Google Apps Script Web App URL

• GAS_API_KEY : API key for accessing Google Apps Script Web App

You can set these environment variables in the .env file:

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

If the environment variable is not set, the server will operate in mock mode and will not access the actual Google Spreadsheet.

How to use

Standalone startup

npm start

Integration with Claude for Desktop

Add the following to your Claude for Desktop configuration file ( claude_desktop_config.json ):

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

To set an environment variable, add env field as follows:

{
  "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"
      }
    }
  }
}

The configuration file is located here:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %AppData%\\Claude\\claude_desktop_config.json

Test with MCP Inspector

npx @modelcontextprotocol/inspector node build/index.js

Tools provided

getSpreadsheet

Gets basic information about a spreadsheet and a list of the sheets it contains.

Input parameters :

• url : The URL of the spreadsheet

output :

• Spreadsheet name, ID, list of sheets (including number of rows and columns)

getSheetData

Gets data from a specific sheet in a spreadsheet.

Input parameters :

• url : The URL of the spreadsheet

• sheetName : The name of the sheet to get

output :

• Sheet data (Markdown table format)

development

Project Structure

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

test

# 単体テスト実行
npm test

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

Integration with Google Apps Script

In actual use, this server works in conjunction with a Google Apps Script Web App:

1. Create a Web App with Google Apps Script

2. Implement an API to access the spreadsheet on the web app side (see api/README.md )

3. Set the API key and link it with the environment variables GAS_WEB_APP_URL and GAS_API_KEY

This approach allows you to avoid the Google authentication flow and maintain the security of your spreadsheet.

If the environment variable is not set, the script will operate in mock mode and return test data.

license

MIT