MCP Gsheets

MCP谷歌表格服务器

](https://www.npmjs.com/package/mcp-gsheets)

用于Google Sheets API集成的模型上下文协议（MCP）服务器。允许直接从MCP客户端（例如，Claude Code、Claude Desktop、Cursor等）读取、写入和管理Google表格文档。

主要特点

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

需求

• v20或更高
• 谷歌云项目 启用了图纸API
• 带有JSON密钥文件的服务帐户

入门指南

快速安装（推荐）

将以下配置添加到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 Code Use the Claude Code CLI to add the MCP Google Sheets server (guide):

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

Claude Desktop

添加到您的Claude Desktop配置中：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %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"
      }
    }
  }
}

Cursor

首选 Cursor Settings → MCP → New MCP Server.使用上面提供的配置。

Cline

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

Other MCP Clients

对于其他MCP客户端，请使用上面显示的标准配置格式。确保 command 设置为 npx 并包括用于Google Cloud身份验证的环境变量。

谷歌云设置

1. 首选 谷歌云控制台
2. 创建新项目或选择现有项目
3. 启用Google Sheets API：

- 导航到“API和服务”→ “图书馆” - 搜索“Google Sheets API”并单击“启用”

1. 创建服务帐户：

- 转到“API和服务”→ “凭据” - 点击“创建凭据”→ “服务帐户” - 在服务帐户列表中，单击 Actions 列→ Manage keys → Add key → Create new key → 选择JSON格式 - 下载JSON密钥文件

1. 分享您的电子表格：

- 打开你的谷歌表格 - 单击共享并添加服务帐户电子邮件（来自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 使用此方法时是可选的

地方发展设置

如果你想开发或参与这个项目，你可以克隆并在本地构建它：

# 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桌面配置
• 创建正确的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

任务运行器（备选）

如果你有 任务 安装：

# 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

1. 在开发模式下运行：

npm run dev  # Watch mode with auto-reload

📋 可用工具

读取数据

写入数据

表单管理

单元格格式

图表

读取/快照工具

🔧 代码质量

代码检查

# 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

❗ 故障排除

常见问题

“身份验证失败”

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

“权限被拒绝”

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

“找不到电子表格”

• 从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 _ sheet \_结构

返回不含任何单元格数据的图纸的轻量级结构/维度元数据。比前者更快、更便宜 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符号数组）

______________________________________________________________________

工作表_格式化_协议

读取范围的单元格格式，并将其作为紧凑的A1Range返回→ 格式对。具有相同格式的相邻单元格被折叠成矩形范围（行程编码），与每个单元格的数据相比，输出减少了90%+。

参数：

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

退货： { range, formatType, rangeCount, data: { "A1:C3": { backgroundColor: {...} }, ... } }

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

______________________________________________________________________

图纸_get_full_sheet_snapshot

在一个API调用中返回所有结构和格式元数据的主一次工具。

参数：

• spreadsheetId （必填）：电子表格的ID
• sheetName （必填）：工作表名称（选项卡）
• includeFormattingRange （可选）：如果提供（例如。 "A1:Z100")，响应中包含每个单元格的格式
• useEffectiveFormat （可选）：在包含单元格格式时，使用effectiveFormat而不是userEnteredFormat（默认值： false)
• fields （可选）：要返回的格式字段名数组，例如。 ["backgroundColor", "textFormat"] -减少API传输大小和响应大小
• compactMode （可选）：当 true，相同的相邻单元格被折叠成矩形范围（RLE）。将典型的85×28纸张从约60000行减少到约500行（默认值： false)

______________________________________________________________________

sheets_insert_rows

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

参数：

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

示例：

// 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", "john@example.com"],
    ["Jane", "Smith", "jane@example.com"],
    ["Bob", "Johnson", "bob@example.com"]
  ]
}

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

📋 更新日志

看 更改日志.md 查看每个版本的更改列表。

🤝 贡献

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 运行测试和梳理(npm run check)
4. 提交您的更改(git commit -m 'Add some amazing feature')
5. 推到分支(git push origin feature/amazing-feature)
6. 打开拉取请求

👤 作者

托马斯 格拉斯尔 - 托马斯格拉斯

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。