MCP Google Sheets Server

MCP Google Sheets 服务

用于集成 Google Sheets API 的模型上下文协议（MCP）服务。可让你直接通过 MCP 客户端（例如 Claude Code、Claude Desktop、Cursor 等）读取、写入和管理 Google Sheets 文档。

主要功能

• 完整的 Google Sheets 集成：读取、写入和管理电子表格
• 高级操作：批量操作、格式设置、图表和条件格式
• 灵活的身份验证：支持基于文件的凭据和 JSON 字符串凭据
• 适用于生产环境：使用 TypeScript 构建，具备全面的错误处理和完整的测试覆盖

要求

• Node.js v22 或更高版本
• 启用了 Sheets API 的 Google Cloud 项目
• 带有 JSON 密钥文件的服务账号
• npm

开始使用

快速安装（推荐）

将以下配置添加到 MCP 客户端：

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "npx",
      "args": ["-y", "mcp-gsheets@latest"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
      }
    }
  }
}

说明

使用 mcp-gsheets@latest 可确保 MCP 客户端始终使用最新版 MCP Google Sheets 服务。

MCP 客户端配置

claude mcp add mcp-gsheets npx mcp-gsheets@latest

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "npx",
      "args": ["mcp-gsheets@latest"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "npx",
      "args": ["-y", "mcp-gsheets@latest"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
      }
    }
  }
}

Google Cloud 设置

1. 前往 Google Cloud Console
2. 创建新项目或选择现有项目
3. 启用 Google Sheets API：
   • 前往“APIs & Services” → “Library”
   • 搜索“Google Sheets API”，然后点击“Enable”
4. 创建服务账号：
   • 前往“APIs & Services” → “Credentials”
   • 点击“Create Credentials” → “Service Account”
   • 在服务账号列表中，点击 Actions 列中的三个点 → Manage keys → Add key → Create new key → 选择 JSON 格式
   • 下载 JSON 密钥文件
5. 分享电子表格：
   • 打开你的 Google Sheet
   • 点击 Share，并添加服务账号邮箱（来自 JSON 文件）
   • 授予“Editor”权限

其他身份验证方式

选项 1：JSON 字符串身份验证

无需使用凭据文件路径，你可以直接以 JSON 字符串的形式提供服务账号凭据。这适用于容器化环境、CI/CD 管道，或你希望避免管理凭据文件的场景。

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "npx",
      "args": ["-y", "mcp-gsheets@latest"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_SERVICE_ACCOUNT_KEY": "{\"type\":\"service_account\",\"project_id\":\"your-project\",\"private_key_id\":\"...\",\"private_key\":\"-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n\",\"client_email\":\"[email protected]\",\"client_id\":\"...\",\"auth_uri\":\"https://accounts.google.com/o/oauth2/auth\",\"token_uri\":\"https://oauth2.googleapis.com/token\",\"auth_provider_x509_cert_url\":\"https://www.googleapis.com/oauth2/v1/certs\",\"client_x509_cert_url\":\"...\"}"
      }
    }
  }
}

注意：使用 GOOGLE_SERVICE_ACCOUNT_KEY 时：

• 整个 JSON 必须位于同一行
• 所有引号都必须用反斜杠转义
• 私钥中的换行符必须表示为 \\n
• 如果 JSON 包含 project_id，可以省略 GOOGLE_PROJECT_ID

选项 2：私钥身份验证（简化版）

最方便用户的方式是直接提供私钥和电子邮件地址。这是最简单的方法，只需要服务账号 JSON 中的两个字段：

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "npx",
      "args": ["-y", "mcp-gsheets@latest"],
      "env": {
        "GOOGLE_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCgR6bvMNOUHZ29\\n+YgbVHAXsT/s+L/jnXTCB193zikCzspSBSfxLu8VRDjkNq9WUoDxizTATzMFNvNf\\n...\\n-----END PRIVATE KEY-----\\n",
        "GOOGLE_CLIENT_EMAIL": "[email protected]"
      }
    }
  }
}

注意：使用 GOOGLE_PRIVATE_KEY 时：

• 私钥中的换行符应表示为 \\n
• 私钥必须包含 -----BEGIN PRIVATE KEY----- 和 -----END PRIVATE KEY----- 标记
• 客户端电子邮件地址应为 JSON 文件中的服务账号电子邮件地址
• 使用此方法时，GOOGLE_PROJECT_ID 是可选的

本地开发设置

如果你想开发或为此项目贡献代码，可以在本地克隆并构建项目：

# Clone the repository
git clone https://github.com/freema/mcp-gsheets.git
cd mcp-gsheets

# Install dependencies
npm install

# Build the project
npm run build

交互式设置脚本

运行交互式设置脚本，配置本地 MCP 客户端：

npm run setup

此脚本将：

• 引导你完成配置
• 自动检测 Node.js 安装（包括 nvm）
• 查找 Claude Desktop 配置
• 创建正确的 JSON 配置
• 可选创建用于开发的 .env 文件

手动本地配置

如果你更倾向于使用本地构建进行手动配置，请在 MCP 客户端配置中添加：

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-gsheets/dist/index.js"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
      }
    }
  }
}

📦 构建与开发

开发命令

# Development mode with hot reload
npm run dev

# Build for production
npm run build

# Type checking
npm run typecheck

# Clean build artifacts
npm run clean

# Run MCP inspector for debugging
npm run inspector

# Run MCP inspector in development mode
npm run inspector:dev

任务运行器（替代方案）

如果已安装 Task：

# Install dependencies
task install

# Build the project
task build

# Run in development mode
task dev

# Run linter
task lint

# Format code
task fmt

# Run all checks
task check

开发设置

1. 创建用于测试的 .env 文件：

cp .env.example .env
# Edit .env with your credentials:
# GOOGLE_PROJECT_ID=your-project-id
# GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
# TEST_SPREADSHEET_ID=your-test-spreadsheet-id

2. 在开发模式下运行：

npm run dev  # Watch mode with auto-reload

🎚️ 使用工具集降低上下文成本

全部 44 个工具在每个会话中总共约占 9,900 个上下文 token， 还未计入模型执行任何操作之前的开销。大多数工作流只需要其中一小部分。 GSHEETS_TOOLSETS 可限制服务公开的工具：

{
  "mcpServers": {
    "gsheets": {
      "command": "npx",
      "args": ["mcp-gsheets"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/key.json",
        "GSHEETS_TOOLSETS": "core,charts"
      }
    }
  }
}

测得的 tools/list 成本：

注意：

• 默认设置保持不变——将 GSHEETS_TOOLSETS 留空即可获得所有工具，与之前完全相同。
• 始终包含 core。 GSHEETS_TOOLSETS=charts 表示“charts 和 core”，而非“仅 charts”——没有 core，服务就无法读取单元格。
• 拼写错误会导致启动错误，而不是静默地减少工具列表。
• GSHEETS_READ_ONLY=true 会移除所有写入工具，并且可以与 GSHEETS_TOOLSETS 组合使用。此设置会在调用工具时强制执行，而不只是在构建列表时执行，因此客户端无法通过指定隐藏工具来写入。

所有工具还带有 MCP 注解（readOnlyHint、destructiveHint、 idempotentHint），因此客户端可以跳过读取操作的确认提示，并在破坏性操作前发出警告。

📋 可用工具

读取数据

写入数据

工作表管理

单元格格式

原生表格

图表

读取／快照工具

🔧 代码质量

代码检查

# Run ESLint
npm run lint

# Fix auto-fixable issues
npm run lint:fix

格式化

# Check formatting with Prettier
npm run format:check

# Format code
npm run format

类型检查

# Run TypeScript type checking
npm run typecheck

❗ 故障排除

常见问题

“Authentication failed”

• 如果使用基于文件的身份验证：确认 JSON 密钥路径是绝对路径且正确
• 如果使用 JSON 字符串身份验证：确保 JSON 已正确转义且有效
• 如果使用私钥身份验证：检查私钥是否包含 BEGIN/END 标记，并且换行符已转义为 \\n
• 确认 GOOGLE_CLIENT_EMAIL 是有效的服务账号邮箱
• 检查 GOOGLE_PROJECT_ID 是否与您的项目匹配（或者在完整 JSON 身份验证的 JSON 中包含该项）
• 确保已启用 Sheets API

“Permission denied”

• 将电子表格共享给服务账号邮箱
• 服务账号需要“Editor”角色
• 检查 JSON 文件中的邮箱（client_email 字段）

“Spreadsheet not found”

• 确认 URL 中的电子表格 ID
• 格式：https://docs.google.com/spreadsheets/d/[SPREADSHEET_ID]/edit

MCP 连接问题

• 确保使用的是构建版本（dist/index.js）
• 检查 Claude Desktop 配置中的 Node.js 路径是否正确
• 查看 Claude Desktop 日志中的错误
• 使用 npm run inspector 进行调试

🔍 查找 ID

电子表格 ID

从 URL 中获取：

https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit
                                        ↑ This is the spreadsheet ID

工作表 ID

使用 sheets_get_metadata 列出所有工作表及其 ID。

📝 提示

1. 始终使用数据副本进行测试
2. 使用批量操作以获得更好的性能
3. 设置适当的权限（只读或编辑）
4. 对于大型操作，请检查速率限制
5. 在操作前使用 sheets_check_access 验证权限

📘 工具详情

sheets_get_sheet_structure

返回工作表的轻量级结构／维度元数据，不包含任何单元格数据。仅需布局信息时，此工具比 sheets_get_full_sheet_snapshot 快得多，成本也更低。

参数：

• spreadsheetId（必填）：电子表格的 ID
• sheetName（必填）：工作表（标签页）的名称

返回： sheetName、sheetId、sheetIndex、tabColor、tabColorStyle、dimensions（rowCount、columnCount）、frozen（rowCount、columnCount）、columnWidths（像素大小数组）、rowHeights（像素大小数组）、hiddenColumns（从 0 开始的索引）、hiddenRows（从 0 开始的索引）、mergeCount、merges（A1 表示法数组）

sheets_get_formatting_compact

读取某个范围的单元格格式，并以紧凑的 A1Range → 格式键值对形式返回。格式相同的相邻单元格会合并为矩形范围（游程编码），与逐单元格数据相比，可将输出减少 90 %+。

参数：

• spreadsheetId（必填）：电子表格的 ID
• sheetName（必填）：工作表（标签页）的名称
• range（必填）：不带工作表前缀的范围，例如 "A1:Z85"
• useEffectiveFormat（可选）：false（默认）= userEnteredFormat（仅包含明确设置的覆盖项，输出更小）；true = effectiveFormat（包含所有继承的默认值）
• fields（可选）：要包含的格式字段名称数组，例如 ["backgroundColor", "textFormat", "borders"]

返回： { range, formatType, rangeCount, data: { "A1:C3": { backgroundColor: {...} }, ... } }

支持的字段： backgroundColor、backgroundColorStyle、textFormat、horizontalAlignment、verticalAlignment、wrapStrategy、textRotation、numberFormat、padding、borders

sheets_get_full_sheet_snapshot

一站式主工具，通过一次 API 调用返回所有结构和格式元数据。

参数：

• spreadsheetId（必填）：电子表格的 ID
• sheetName（必填）：工作表（标签页）的名称
• includeFormattingRange（可选）：如果提供（例如 "A1:Z100"），响应中将包含单元格格式
• useEffectiveFormat（可选）：包含单元格格式时，使用 effectiveFormat 而非 userEnteredFormat（默认值：false）
• fields（可选）：要返回的格式字段名称数组，例如 ["backgroundColor", "textFormat"] — 可减少 API 传输和响应的数据量
• compactMode（可选）：设为 true 时，将相邻且相同的单元格合并为矩形范围（RLE）。可将典型的 85×28 工作表从约 60 000 行缩减至约 500 行（默认值：false）

sheets_insert_rows

在电子表格的指定位置插入新行，并可选择填入数据。

参数：

• spreadsheetId（必填）：电子表格的 ID
• range（必填）：用于定位的 A1 表示法锚点（例如 "Sheet1!A5"）
• rows（可选）：要插入的行数（默认值：1）
• position（可选）：锚点行之前的 'BEFORE' 或之后的 'AFTER'（默认值：'BEFORE'）
• inheritFromBefore（可选）：是否继承前一行的格式（默认值：false）
• values（可选）：用于填充新插入行的二维值数组
• valueInputOption（可选）：'RAW' 或 'USER_ENTERED'（默认值：'USER_ENTERED'）

示例：

// Insert 1 empty row before row 5
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "Sheet1!A5"
}

// Insert 3 rows after row 10 with data
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "Sheet1!A10",
  "rows": 3,
  "position": "AFTER",
  "values": [
    ["John", "Doe", "[email protected]"],
    ["Jane", "Smith", "[email protected]"],
    ["Bob", "Johnson", "[email protected]"]
  ]
}

sheets_delete_columns

使用整列 A1 范围删除工作表中的一列或多列。

参数：

• spreadsheetId（必填）：电子表格的 ID
• range（必填）：要删除的整列 A1 范围（例如 "Sheet1!B:D" 或 "Sheet1!C:C"）

示例：

// Delete columns B through D from Sheet1
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "Sheet1!B:D"
}

// Delete a single column from the first sheet
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "C:C"
}

sheets_delete_rows

使用整行 A1 范围删除工作表中的一行或多行。

参数：

• spreadsheetId（必填）：电子表格的 ID
• range（必填）：要删除的整行 A1 范围（例如 "Sheet1!2:4" 或 "Sheet1!3:3"）

示例：

// Delete rows 2 through 4 from Sheet1
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "Sheet1!2:4"
}

// Delete a single row from the first sheet
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "3:3"
}

📋 更新日志

请参阅 CHANGELOG.md，了解各版本的更改列表。

🤝 参与贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 运行测试和 lint（npm run check）
4. 提交更改（git commit -m 'Add some amazing feature'）
5. 推送到分支（git push origin feature/amazing-feature）
6. 创建 Pull Request

👤 作者

Tomáš Grásl - tomasgrasl.cz

📄 许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。