Spreadsheet MCP Server

Spreadsheet MCP Server

Este proyecto es un servidor de Model Context Protocol (MCP) para acceder a los datos de Google Spreadsheet. Permite que los LLM utilicen directamente la información de las hojas de cálculo.

Funcionalidades

• Obtención de información básica de la hoja de cálculo (lista de hojas, etc.)
• Obtención de datos de una hoja específica y formateo en formato Markdown
• Integración con clientes MCP (como Claude for Desktop)

Instalación

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

Configuración de variables de entorno

Para la configuración del servidor se utilizan las siguientes variables de entorno:

• GAS_WEB_APP_URL: URL de la Web App de Google Apps Script
• GAS_API_KEY: Clave de API para acceder a la Web App de Google Apps Script

Estas variables de entorno se pueden configurar en el archivo .env:

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

Si las variables de entorno no están configuradas, el servidor funciona en modo simulado y no accede a hojas de cálculo reales de Google.

Cómo usar

Inicio independiente

npm start

Integración con Claude for Desktop

Añada lo siguiente al archivo de configuración de Claude for Desktop (claude_desktop_config.json):

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

Para configurar las variables de entorno, añada el campo env de la siguiente manera:

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

El archivo de configuración se encuentra en las siguientes ubicaciones:

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

Pruebas con MCP Inspector

npx @modelcontextprotocol/inspector node build/index.js

Herramientas proporcionadas

getSpreadsheet

Obtiene información básica de la hoja de cálculo y la lista de hojas que contiene.

Parámetros de entrada:

• url: URL de la hoja de cálculo

Salida:

• Nombre de la hoja de cálculo, ID y lista de hojas (incluyendo número de filas y columnas)

getSheetData

Obtiene los datos de una hoja específica de la hoja de cálculo.

Parámetros de entrada:

• url: URL de la hoja de cálculo
• sheetName: Nombre de la hoja a obtener

Salida:

• Datos de la hoja (en formato de tabla Markdown)

Desarrollo

Estructura del proyecto

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

Pruebas

# 単体テスト実行
npm test

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

Sobre la integración con Google Apps Script

Este servidor funciona en conjunto con la Web App de Google Apps Script en su uso real:

1. Crear una Web App en Google Apps Script
2. Implementar una API que acceda a la hoja de cálculo desde la aplicación web (consulte api/README.md)
3. Configurar la clave de API y conectar mediante las variables de entorno GAS_WEB_APP_URL y GAS_API_KEY

Este enfoque evita el flujo de autenticación de Google y mantiene la seguridad de la hoja de cálculo.

Si las variables de entorno no están configuradas, el servidor funciona en modo simulado y devuelve datos de prueba.

Licencia

MIT