Google Sheets MCP Server

这是一个用于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  # 在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/                  # 虚拟环境
├── google_sheets.py        # 主服务器实现
├── pyproject.toml         # 项目配置和依赖项
├── tests/                 # 测试文件
└── README.md             # 本文件

添加新功能

1. 向GoogleSheetsMCP类添加新的工具方法
2. 使用@mcp.tool()装饰它们
3. 更新README以包含新功能的文档

运行测试

pytest

故障排除

1. 服务器连接问题

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

2. 认证问题

   • 确保OAuth凭证有效
   • 检查你的电子邮件是否被添加为测试用户
   • 尝试删除token.json并重新认证

3. API错误

   • 验证Google Sheets API是否已启用
   • 检查API配额和限制
   • 查看错误日志以了解具体问题

贡献

1. 分叉仓库
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建拉取请求

许可证

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