内容
# 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 控制台的 OAuth 2.0 凭证
- Claude Desktop 应用程序
- `uv` 包管理器（推荐）
## 安装
1. 克隆仓库：
```bash
git clone https://github.com/yourusername/google-sheets-mcp-server.git
cd google-sheets-mcp-server
```
2. 创建并激活虚拟环境：
```bash
python -m venv .venv
source .venv/bin/activate # 在 Windows 上：.venv\Scripts\activate
```
3. 使用 `uv` 安装依赖项：
```bash
uv pip install -e .
```
4. 设置 Google Cloud 凭证：
- 访问 [Google Cloud 控制台](https://console.cloud.google.com/)
- 创建新项目或选择现有项目
- 启用 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` 中添加以下内容：
```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 身份验证：
```bash
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
### 运行测试
```bash
pytest
```
## 故障排除
1. **服务器连接问题**
- 检查服务器是否正在运行
- 验证配置中的凭证路径
- 检查 Claude Desktop 中的日志
2. **身份验证问题**
- 确保 OAuth 凭证有效
- 检查您的电子邮件是否已添加为测试用户
- 尝试删除 token.json 并重新身份验证
3. **API 错误**
- 验证 Google Sheets API 是否已启用
- 检查 API 配额和限制
- 查看错误日志以获取特定问题
## 贡献
1. 分叉仓库
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建拉取请求
## 许可证
该项目根据 MIT 许可证授权 - 有关详细信息，请参阅 LICENSE 文件。
MCP 市场