Hosakakeigo Spreadsheet MCP Server

🚀 Google Spreadsheet MCP Server

This project is a Model Context Protocol (MCP) server for accessing Google Spreadsheet data, enabling LLMs to directly utilize spreadsheet information.

🚀 Quick Start

This is a Model Context Protocol (MCP) server designed to access Google Spreadsheet data, allowing LLMs to directly utilize spreadsheet information.

✨ Features

• Retrieve basic spreadsheet information (e.g., list of worksheets).
• Fetch data from specific worksheets and format it in Markdown.
• Integrate with MCP clients (e.g., Desktop version of Claude).

📦 Installation

# Clone the repository
git clone https://github.com/your-username/spreadsheet-mcp-server.git
cd spreadsheet-mcp-server

# Install dependencies
npm install

# Copy the example environment file
cp .env.example .env
# Edit the .env file and set GAS_WEB_APP_URL and GAS_API_KEY

# Build the project
npm run build

💻 Usage Examples

Standalone Launch

npm start

Integration with Desktop Version of Claude

Add the following content to the configuration file (claude_desktop_config.json) of the Desktop version of Claude:

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

To set environment variables, add the env field to the configuration file as follows:

{
  "mcpServers": {
    "spreadsheet": {
      "command": "node",
      "args": ["<Absolute path to the 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 location of the configuration file is as follows:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Using the MCP Server

To access spreadsheet data, you can call the MCP service in your code:

import { createMCPClient } from 'mcp-client'

const mcp = await createMCPClient('spreadsheet')
await mcp.query('Get spreadsheet content', {
  spreadsheetId: '<Spreadsheet ID>',
  sheetName: '<Worksheet name>'
})

📚 Documentation

Environment Variable Configuration

The environment variables required for the server to run are as follows:

• GAS_WEB_APP_URL: The URL of the Google Apps Script Web App.
• GAS_API_KEY: The API key for accessing the Google Apps Script Web App.

These environment variables can be set 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 variables are not configured, the server will run in simulation mode and will not actually access Google Spreadsheets.

Development Information

Project Structure

The project folder structure is as follows:

src/
  |- api/                   # Define interfaces for interacting with the Web App
  |- mock/                 # Mock data (used when environment variables are not configured)
  |- services/             # Core logic for processing spreadsheet data
    |- SpreadsheetService.ts   # Spreadsheet data processing class

Development Steps

1. Install dependencies:

npm install

2. Start the development server:

npm run dev

Testing Instructions

To run tests:

npm test

Integrating with Google Apps Script Web App

To use Google Spreadsheet data, follow these steps:

1. Create a Google Apps Script Web App: Creation Guide
2. Implement an API for accessing spreadsheets in the Web App (refer to api/README.md)
3. Configure the environment variables GAS_WEB_APP_URL and GAS_API_KEY

By doing so, you can securely use spreadsheet data without Google authentication. If the environment variables are not configured, the server will run in simulation mode and return test data.