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 控制台的 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 文件。