内容
# xlsx-drive-mcp
允许AI代理（如Claude等）读取和写入存储在Google Drive上的`.xlsx`文件。填补了Excel MCP服务器（仅限本地文件）和Google Drive MCP服务器（仅限原生Google Sheets）的空白。
## 功能特点
- 读取/写入单元格值、公式、格式、图表
- 完整的表格管理（创建、删除、重命名、复制）
- Google Drive身份验证，无需额外设置，适用于现有的workspace-mcp用户
- 并发编辑冲突检测
## 安装
```bash
pip install xlsx-drive-mcp
```
需要Python 3.10+。
## 身份验证
### 选项A：现有的workspace-mcp用户（无需额外设置）
如果您已经使用[workspace-mcp](https://workspacemcp.com)，则会自动重用凭证。跳至Claude配置。
### 选项B：独立设置
1. 访问[Google Cloud Console](https://console.cloud.google.com/apis/credentials)
2. 创建一个项目（或使用现有的项目）
3. 启用**Google Drive API**
4. 创建凭证：**OAuth客户端ID** → **桌面应用程序**
5. 下载客户端ID和密码，然后：
```bash
export GOOGLE_CLIENT_ID=your_client_id
export GOOGLE_CLIENT_SECRET=your_client_secret
xlsx-drive-mcp auth --user you@example.com
```
这将打开浏览器，完成OAuth流程，并将凭证存储在`~/.xlsx-drive-mcp/credentials/you@example.com.json`。
**将以下内容添加到您的全局`.gitignore`：**
```
~/.xlsx-drive-mcp/
```
## Claude 配置
```json
{
"mcpServers": {
"xlsx-drive": {
"command": "xlsx-drive-mcp",
"args": ["--user", "your-actual-email@example.com"]
}
}
}
```
将`your-actual-email@example.com`替换为您身份验证使用的电子邮件地址。如果您只有一个凭证文件，则可以省略`--user`。
## 范围说明
- **workspace-mcp用户**继承workspace-mcp的作用域，通常是完全的Drive访问权限。
- **独立用户**获得`drive.file`作用域 - 仅限访问此应用程序创建或打开的文件。
使用`drive.file`作用域时，`list_xlsx_files`仅返回您之前使用此工具打开的文件。要搜索所有Drive文件，请使用完全的`drive`作用域或workspace-mcp路径。
## 查找folder_id
在浏览器中打开任意Drive文件夹。网址类似于：
`https://drive.google.com/drive/folders/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74`
`folder_id`是最后一部分：`1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74`。
## 重要警告
- **`write_range`覆盖公式单元格**会用静态值替换公式。
- **`read_range`且`data_only=true`**（默认）返回缓存的值，而不是实时的公式结果。
使用`data_only=false`获取公式字符串。
- **`copy_sheet`**静默删除复制的表格中的图表和图像（openpyxl限制）。
- **`delete_xlsx`**将文件移至回收站。用户有30天的时间从Drive UI恢复它。
## 工具参考
| 工具 | 描述 |
|---|---|
| `list_xlsx_files` | 在Drive中搜索xlsx文件 |
| `get_xlsx_info` | 表格名称、数据维度、命名范围 |
| `create_xlsx` | 在Drive上创建新的空白xlsx文件 |
| `delete_xlsx` | 将xlsx文件移至回收站 |
| `list_sheets` | 列出所有表格 |
| `create_sheet` | 添加新的表格 |
| `delete_sheet` | 删除表格 |
| `rename_sheet` | 重命名表格 |
| `copy_sheet` | 复制表格（删除图表/图像） |
| `read_range` | 读取单元格值 |
| `write_range` | 写入单元格值 |
| `append_rows` | 在最后一行数据下追加行 |
| `clear_range` | 清除值，保留格式 |
| `read_format` | 读取单元格格式（颜色、粗体、边框） |
| `format_range` | 对范围应用格式 |
| `set_column_width` | 设置列宽 |
| `set_row_height` | 设置行高 |
| `merge_cells` | 合并单元格范围 |
| `unmerge_cells` | 取消合并单元格范围 |
| `create_chart` | 创建条形图、折线图、饼图或散点图 |
| `write_formula` | 将公式写入单个单元格 |
## 故障排除
**MCP服务器无法启动/工具未找到：**
Claude Desktop将MCP服务器作为后台进程启动，没有可见的输出。
要查看服务器日志，请手动运行服务器：
```bash
xlsx-drive-mcp --user your@email.com
```
任何错误都将在终端中显示。
**`list_xlsx_files`返回无结果：**
使用`drive.file`作用域时，只有此应用程序创建或之前打开的文件是可见的。
使用`get_xlsx_info(file_id)`直接获取一个已知的`file_id`，而不是从Drive URL中。
**共享Drive / 团队Drive：**
v1中未正式测试。可能有效；不支持。如果您测试，请报告问题。
**服务账号：**
v1中不支持。作为路线图项目跟踪。
## 许可证
MIT
