JinDaGe - mcp-gsheets MCP Details

article

README

🚀 MCP Google Sheets Server

这是一个用于集成 Google Sheets API 的模型上下文协议（MCP）服务器。借助它，你可以直接从 MCP 客户端（如 Claude Desktop）读取、写入和管理 Google Sheets 文档。

🚀 快速开始

1. 前提条件

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

2. 安装

# 克隆仓库
git clone https://github.com/freema/mcp-gsheets.git
# 或者使用 SSH
# git clone git@github.com:freema/mcp-gsheets.git
cd mcp-gsheets

# 安装依赖
npm install

# 构建项目
npm run build

3. Google Cloud 设置

访问 Google Cloud 控制台。
创建一个新项目或选择现有项目。
启用 Google Sheets API：
- 导航到“API 和服务”→“库”。
- 搜索“Google Sheets API”并点击“启用”。
创建服务账户：
- 转到“API 和服务”→“凭据”。
- 点击“创建凭据”→“服务账户”。
- 下载 JSON 密钥文件。
共享你的电子表格：
- 打开你的 Google 表格。
- 点击“共享”并添加服务账户的电子邮件（来自 JSON 文件）。
- 授予“编辑者”权限。

4. 配置 MCP 客户端

简易设置（推荐）

运行交互式设置脚本：

npm run setup

这将：

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

手动设置

如果你更喜欢手动配置，请将以下内容添加到你的 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": "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"
            }
        }
    }
}

添加配置后，重启 Claude Desktop。

📦 构建与开发

开发命令

# 开启热重载的开发模式
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

# 运行代码检查器
task lint

# 格式化代码
task fmt

# 运行所有检查
task check

开发设置

创建用于测试的 .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

在开发模式下运行：

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 - 向表格追加行
sheets_clear_values - 清除单元格内容

表格管理

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

单元格格式设置

sheets_format_cells - 设置单元格格式（颜色、字体、对齐方式、数字格式）
sheets_update_borders - 添加或修改单元格边框
sheets_merge_cells - 合并单元格
sheets_unmerge_cells - 取消合并之前合并的单元格
sheets_add_conditional_formatting - 添加条件格式规则

🔧 代码质量

代码检查

# 运行 ESLint
npm run lint

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

代码格式化

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

# 格式化代码
npm run format

类型检查

# 运行 TypeScript 类型检查
npm run typecheck

❗ 故障排除

常见问题

“身份验证失败”

验证 JSON 密钥路径是否为绝对路径且正确。
检查 GOOGLE_PROJECT_ID 是否与你的项目匹配。
确保 Sheets 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
                                        ↑ 这就是电子表格 ID

工作表 ID

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

📝 提示

始终使用数据副本进行测试。
使用批量操作以提高性能。
设置适当的权限（只读 vs 编辑）。
对于大型操作，检查速率限制。
在操作前使用 sheets_check_access 验证权限。

🤝 贡献代码

分叉仓库。
创建你的功能分支（git checkout -b feature/amazing-feature）。
运行测试和代码检查（npm run check）。
提交你的更改（git commit -m 'Add some amazing feature'）。
推送到该分支（git push origin feature/amazing-feature）。
打开一个拉取请求。

📄 许可证

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

mcp-gsheets