Google Sheets MCP Server

Google Sheets MCP 服务

一个用于 Google Sheets 的模型上下文协议（MCP）服务，可让 Claude Desktop 直接与 Google Sheets 交互。此服务提供工具，可通过 Claude Desktop 创建、读取、写入和管理 Google Sheets。

功能

• 创建新的 Google Sheets
• 读取和写入现有工作表中的数据
• 设置单元格和区域的格式
• 添加和删除工作表
• 写入公式
• 搜索工作表
• 列出可用工作表

前置条件

• Python 3.10 或更高版本
• 已启用 Google Sheets API 的 Google Cloud 项目
• 从 Google Cloud Console 获取的 OAuth 2.0 凭据
• Claude Desktop 应用程序
• uv 包管理器（推荐）

安装

1. 克隆代码库：

git clone https://github.com/yourusername/google-sheets-mcp-server.git
cd google-sheets-mcp-server

2. 创建并激活虚拟环境：

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. 使用 uv 安装依赖项：

uv pip install -e .

4. 设置 Google Cloud 凭据：
   • 前往 Google Cloud Console
   • 创建新项目或选择现有项目
   • 启用 Google Sheets API 和 Google Drive API
   • 创建 OAuth 2.0 凭据（桌面应用）
   • 下载凭据并保存为 ~/.config/google_sheets_mcp/google-sheets-mcp.json

配置

1. 配置 Claude Desktop：
   • 打开 Claude Desktop 设置
   • 将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "google_sheets": {
      "command": "/path/to/your/.venv/bin/python",
      "args": [
        "/path/to/your/google_sheets.py",
        "--credentials-path",
        "/Users/yourusername/.config/google_sheets_mcp/google-sheets-mcp.json",
        "--log-level",
        "DEBUG"
      ]
    }
  }
}

2. 首次设置：
   • 手动运行服务以完成 OAuth 身份验证：

python google_sheets.py --credentials-path ~/.config/google_sheets_mcp/google-sheets-mcp.json

• 按照浏览器中的提示授权应用程序
• 令牌将自动保存，以供日后使用

使用方法

完成设置后，你可以在 Claude Desktop 中使用以下命令：

• 创建新工作表：create_sheet(title: str)
• 设置单元格格式：format_range(file_id: str, range: str, format: dict)
• 写入公式：write_formula(file_id: str, range: str, formula: str)
• 添加工作表：add_sheet(file_id: str, title: str)
• 删除工作表：delete_sheet(file_id: str, sheet_id: int)
• 获取工作表属性：get_sheet_properties(file_id: str)

开发

项目结构

google-sheets-mcp-server/
├── .venv/                  # Virtual environment
├── google_sheets.py        # Main server implementation
├── pyproject.toml         # Project configuration and dependencies
├── tests/                 # Test files
└── README.md             # This file

添加新功能

1. 在 GoogleSheetsMCP 类中添加新的工具方法
2. 使用 @mcp.tool() 装饰这些方法
3. 在 README 中更新新功能的文档

运行测试

pytest

故障排除

1. 服务连接问题

   • 检查服务是否正在运行
   • 验证配置中的凭据路径
   • 检查 Claude Desktop 中的日志

2. 身份验证问题

   • 确保 OAuth 凭据有效
   • 检查是否已将你的电子邮件地址添加为测试用户
   • 尝试删除 token.json 并重新进行身份验证

3. API 错误

   • 确认已启用 Google Sheets API
   • 检查 API 配额和限制
   • 查看错误日志，了解具体问题

贡献

1. Fork 代码库
2. 创建功能分支
3. 提交更改
4. 将更改推送到分支
5. 创建 Pull Request

许可证

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