Spreadsheet MCP Server

Spreadsheet MCP Server

Este projeto é um servidor Model Context Protocol (MCP) para acessar dados do Google Spreadsheet. Ele permite que LLMs utilizem diretamente as informações das planilhas.

Funcionalidades

• Obtenção de informações básicas da planilha (como lista de abas)
• Obtenção de dados de uma aba específica e formatação em Markdown
• Integração com clientes MCP (como Claude for Desktop)

Instalação

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

Configuração de variáveis de ambiente

As seguintes variáveis de ambiente são usadas para configurar o servidor:

• GAS_WEB_APP_URL: URL do Google Apps Script Web App
• GAS_API_KEY: Chave de API para acesso ao Google Apps Script Web App

Essas variáveis de ambiente podem ser configuradas no arquivo .env:

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

Se as variáveis de ambiente não estiverem configuradas, o servidor opera em modo de simulação (mock) e não acessa planilhas reais do Google.

Como usar

Execução autônoma (standalone)

npm start

Integração com Claude for Desktop

Adicione o seguinte ao arquivo de configuração do Claude for Desktop (claude_desktop_config.json):

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

Para configurar variáveis de ambiente, adicione o campo env da seguinte forma:

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

O arquivo de configuração está localizado em:

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

Teste com o MCP Inspector

npx @modelcontextprotocol/inspector node build/index.js

Ferramentas fornecidas

getSpreadsheet

Obtém as informações básicas da planilha e a lista de abas contidas nela.

Parâmetros de entrada:

• url: URL da planilha

Saída:

• Nome da planilha, ID e lista de abas (incluindo número de linhas e colunas)

getSheetData

Obtém os dados de uma aba específica da planilha.

Parâmetros de entrada:

• url: URL da planilha
• sheetName: Nome da aba a ser obtida

Saída:

• Dados da aba (em formato de tabela Markdown)

Desenvolvimento

Estrutura do projeto

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

Testes

# 単体テスト実行
npm test

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

Sobre a integração com Google Apps Script

Em uso real, este servidor opera em conjunto com o Web App do Google Apps Script:

1. Criar um Web App no Google Apps Script
2. Implementar uma API no lado do Web App para acessar a planilha (consulte api/README.md)
3. Configurar a chave de API e integrar por meio das variáveis de ambiente GAS_WEB_APP_URL e GAS_API_KEY

Essa abordagem evita o fluxo de autenticação do Google e mantém a segurança da planilha.

Se as variáveis de ambiente não estiverem configuradas, o servidor opera em modo de simulação (mock) e retorna dados de teste.

Licença

MIT