MCP Google Sheets Server

<a href="https://glama.ai/mcp/servers/@freema/mcp-gsheets"> <img width="380" height="200" src="https://gips2.baidu.com/it/u=127458431,1851253543&fm=3081&app=3081&f=PNG?w=760&h=400" /> </a>

一个用于集成 Google Sheets API 的 Model Context Protocol (MCP) 服务器。允许从您的 MCP 客户端（例如 Claude Code、Claude Desktop、Cursor 等）直接读取、写入和管理 Google Sheets 文档。

主要特性

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

要求

• Node.js v18 或更高版本
• 启用了 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"
      }
    }
  }
}

[!NOTE] 使用 mcp-gsheets@latest 可确保您的 MCP 客户端始终使用最新版本的 MCP Google Sheets 服务器。

MCP 客户端配置

<details> <summary>Claude Code</summary> 使用 Claude Code CLI 添加 MCP Google Sheets 服务器（[指南](https://docs.anthropic.com/en/docs/claude-code/mcp)）：

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

添加后，编辑您的 Claude Code 配置以添加所需的环境变量：

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

</details> <details> <summary>Claude Desktop</summary>

在您的 Claude Desktop 配置中添加：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.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"
      }
    }
  }
}

</details> <details> <summary>Cursor</summary>

转到 Cursor 设置 → MCP → 新建 MCP 服务器。使用上面提供的配置。

</details> <details> <summary>Cline</summary>

遵循 https://docs.cline.bot/mcp/configuring-mcp-servers 并使用上面提供的配置。

</details> <details> <summary>其他 MCP 客户端</summary>

对于其他 MCP 客户端，请使用上述标准配置格式。确保 command 设置为 npx 并包括 Google Cloud 认证所需的环境变量。

</details>

Google Cloud 设置

1. 转到 Google Cloud 控制台
2. 创建新项目或选择现有项目
3. 启用 Google Sheets API：
   • 导航到 "APIs & Services" → "库"
   • 搜索 "Google Sheets API" 并点击 "启用"
4. 创建服务帐户：
   • 转到 "APIs & Services" → "凭据"
   • 点击 "创建凭据" → "服务帐户"
   • 下载 JSON 密钥文件
5. 共享您的电子表格：
   • 打开您的 Google 表格
   • 点击共享并添加服务帐户电子邮件（来自 JSON 文件）
   • 授予 "编辑者" 权限

替代身份验证方法

选项 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\":\"...@....iam.gserviceaccount.com\",\"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": "spreadsheet@your-project.iam.gserviceaccount.com"
      }
    }
  }
}

注意：当使用 GOOGLE_PRIVATE_KEY 时：

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

本地开发设置

如果您想开发或为此项目做出贡献，可以克隆并在本地构建它：

# 克隆仓库
git clone https://github.com/freema/mcp-gsheets.git
cd mcp-gsheets

# 安装依赖
npm install

# 构建项目
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"
      }
    }
  }
}

📦 构建与开发

开发命令

# 开发模式带热重载
npm run dev

# 生产构建
npm run build

# 类型检查
npm run typecheck

# 清理构建工件
npm run clean

# 运行 MCP 检查器进行调试
npm run inspector

# 在开发模式下运行 MCP 检查器
npm run inspector:dev

任务运行器（替代方案）

如果您已安装 Task：

# 安装依赖
task install

# 构建项目
task build

# 在开发模式下运行
task dev

# 运行 linter
task lint

# 格式化代码
task fmt

# 运行所有检查
task check

开发设置

1. 为测试创建 .env 文件：

cp .env.example .env
# 编辑 .env 以包含您的凭证：
# 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  # 监控模式自动重新加载

📋 可用工具

读取数据

• sheets_get_values - 从范围读取
• sheets_batch_get_values - 从多个范围读取
• sheets_get_metadata - 获取电子表格信息
• sheets_check_access - 检查访问权限

写入数据

• sheets_update_values - 写入范围
• sheets_batch_update_values - 写入多个范围
• sheets_append_values - 在表中追加行（注意：默认 insertDataOption 是 OVERWRITE。要插入新行，请设置 insertDataOption: 'INSERT_ROWS'）
• sheets_clear_values - 清除单元格内容
• sheets_insert_rows - 在特定位置插入新行，可选数据

电子表格管理

• sheets_insert_sheet - 添加新工作表
• sheets_delete_sheet - 删除工作表
• sheets_duplicate_sheet - 复制工作表
• sheets_copy_to - 复制到另一个电子表格
• sheets_update_sheet_properties - 更新工作表设置

批量操作

• sheets_batch_delete_sheets - 一次删除多个工作表
• sheets_batch_format_cells - 一次格式化多个单元格范围

单元格格式化

• sheets_format_cells - 格式化单元格（颜色、字体、对齐方式、数字格式）
• sheets_update_borders - 添加或修改单元格边框
• sheets_merge_cells - 合并单元格
• sheets_unmerge_cells - 分离先前合并的单元格
• sheets_add_conditional_formatting - 添加条件格式规则

图表

• sheets_create_chart - 创建各种类型的图表
• sheets_update_chart - 修改现有图表
• sheets_delete_chart - 删除图表

🔧 代码质量

代码检查

# 运行 ESLint
npm run lint

# 修复自动修复的问题
npm run lint:fix

格式化

# 使用 Prettier 检查格式
npm run format:check

# 格式化代码
npm run format

类型检查

# 运行 TypeScript 类型检查
npm run typecheck

❗ 故障排除

常见问题

“身份验证失败”

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

“权限被拒绝”

• 将电子表格与服务帐户电子邮件共享
• 服务帐户需要“编辑者”角色
• 检查 JSON 文件中的电子邮件（client_email 字段）

“电子表格未找到”

• 验证电子表格 ID 从 URL
• 格式：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
                                        ↑ 这是电子表格 ID

工作表 ID

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

📝 提示

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

📘 工具详情

sheets_insert_rows

在电子表格中的特定位置插入新行，可选数据。

参数：

• spreadsheetId（必需）：电子表格的 ID
• range（必需）：插入行的 A1 标记锚点（例如，“Sheet1!A5”）
• rows（可选）：要插入的行数（默认：1）
• position（可选）：在锚定行的“BEFORE”或“AFTER”（默认：“BEFORE”）
• inheritFromBefore（可选）：是否继承前一行的格式（默认：false）
• values（可选）：填充新插入行的二维值数组
• valueInputOption（可选）：'RAW' 或 'USER_ENTERED'（默认：'USER_ENTERED'）

示例：

// 在第 5 行前插入 1 个空行
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "Sheet1!A5"
}

// 在第 10 行后插入 3 行并带有数据
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "Sheet1!A10",
  "rows": 3,
  "position": "AFTER",
  "values": [
    ["John", "Doe", "john@example.com"],
    ["Jane", "Smith", "jane@example.com"],
    ["Bob", "Johnson", "bob@example.com"]
  ]
}

📋 更改日志

查看 CHANGELOG.md 了解每个版本的更改列表。

🤝 贡献

1. 分叉仓库
2. 创建您的功能分支（git checkout -b feature/amazing-feature）
3. 运行测试和代码检查（npm run check）
4. 提交您的更改（git commit -m '添加一些精彩的功能'）
5. 推送到分支（git push origin feature/amazing-feature）
6. 打开拉取请求

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。