🚀 Google Sheets MCP 服务器

这是一个专为 Google Sheets 设计的模型上下文协议 (MCP) 服务器，它让 Claude Desktop 能够直接与 Google Sheets 进行交互。该服务器提供了一系列工具，可用于创建、读取、写入和管理 Google Sheets。

🚀 快速开始

本服务器是为 Google Sheets 量身打造的 MCP 服务器，借助它，Claude Desktop 能与 Google Sheets 直接交互，提供了创建、读取、写入和管理表格的工具。下面为你介绍使用前的安装、配置及使用方法。

✨ 主要特性

• 创建新的 Google 表格
• 读取和写入数据到现有表格
• 格式化单元格和范围
• 添加和删除表格
• 写入公式
• 搜索表格
• 列出可用表格

📦 安装指南

先决条件

• 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

📚 详细文档

配置

配置 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"
      ]
    }
  }
}

首次设置

• 手动运行服务器以完成 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

故障排除

服务器连接问题

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

身份验证问题

• 确保 OAuth 2.0 凭证有效
• 检查应用程序是否有正确的权限
• 确认使用的是最新版本的库和工具

其他问题

• 查看控制台输出以获取详细错误信息
• 确保 Google Sheets API 已正确启用
• 验证所有依赖项是否已安装

💻 使用示例

基础用法

# 这是一个简单的示例，展示了如何使用 google_sheets.py 库进行基本操作。

from google_sheets import GoogleSheetsMCP

# 初始化 MCP 服务器
mcp = GoogleSheetsMCP(credentials_path='path/to/google-sheets-mcp.json')

# 创建新表格
sheet_id = mcp.create_sheet('示例表格')

# 写入数据到表格
mcp.write_formula(sheet_id, 'A1', '=SUM(1,2)')

# 读取单元格内容
value = mcp.read_cell(sheet_id, 'A1')
print(value)  # 输出: 3

# 删除表格
mcp.delete_sheet(sheet_id)

常见问题解答

问：如何处理 OAuth 身份验证错误？ 答：请确保您的 Google Cloud 项目已启用正确的 API，并且凭证文件路径正确。检查控制台输出以获取具体错误信息。

问：无法连接到 Google Sheets？ 答：确认互联网连接正常，Google Sheets API 已启用，并且使用的凭证具有适当权限。

联系方式

如需帮助或报告问题，请访问 项目主页 或发送邮件至 support@yourdomain.com。