# xlsx-drive-mcp

An MCP server that lets AI agents (Claude and others) read and write `.xlsx` files
stored on Google Drive. Fills the gap between Excel MCP servers (local files only)
and Google Drive MCP servers (native Google Sheets only).

## Features

- Read/write cell values, formulas, formatting, charts
- Full sheet management (create, delete, rename, copy)
- Google Drive authentication with zero extra setup for existing workspace-mcp users
- Conflict detection on concurrent edits

## Installation

```bash
pip install xlsx-drive-mcp
```

Requires Python 3.10+.

## Authentication

### Option A: Existing workspace-mcp users (zero extra setup)

If you already use [workspace-mcp](https://workspacemcp.com), credentials are reused
automatically. Skip to Claude Config below.

### Option B: Standalone setup

1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
2. Create a project (or use an existing one)
3. Enable the **Google Drive API**
4. Create credentials: **OAuth client ID** → **Desktop app**
5. Download the client ID and secret, then:

```bash
export GOOGLE_CLIENT_ID=your_client_id
export GOOGLE_CLIENT_SECRET=your_client_secret
xlsx-drive-mcp auth --user you@example.com
```

This opens a browser, completes the OAuth flow, and stores credentials at
`~/.xlsx-drive-mcp/credentials/you@example.com.json`.

**Add to your global `.gitignore`:**
```
~/.xlsx-drive-mcp/
```

## Claude Config

```json
{
  "mcpServers": {
    "xlsx-drive": {
      "command": "xlsx-drive-mcp",
      "args": ["--user", "your-actual-email@example.com"]
    }
  }
}
```

Replace `your-actual-email@example.com` with the email you authenticated with.
If you have only one credential file, `--user` can be omitted.

## Scope note

- **workspace-mcp users** inherit workspace-mcp's scope, which is typically full Drive access.
- **Standalone users** get `drive.file` scope -- access only to files this app created or opened.
  With `drive.file` scope, `list_xlsx_files` only returns files you've previously opened with
  this tool. To search all Drive files, use full `drive` scope or the workspace-mcp path.

## Finding a folder_id

Open any Drive folder in your browser. The URL looks like:
`https://drive.google.com/drive/folders/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74`
The `folder_id` is the last segment: `1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74`.

## Important warnings

- **`write_range` over formula cells** replaces formulas with static values.
- **`read_range` with `data_only=true`** (default) returns cached values, not live formula results.
  Use `data_only=false` to get formula strings instead.
- **`copy_sheet`** silently drops charts and images from the copied sheet (openpyxl limitation).
- **`delete_xlsx`** moves the file to trash. The user has 30 days to recover it from Drive UI.

## Tool reference

| Tool | Description |
|---|---|
| `list_xlsx_files` | Search Drive for xlsx files |
| `get_xlsx_info` | Sheet names, data dimensions, named ranges |
| `create_xlsx` | Create a new blank xlsx on Drive |
| `delete_xlsx` | Move an xlsx to trash |
| `list_sheets` | List all sheets |
| `create_sheet` | Add a new sheet |
| `delete_sheet` | Remove a sheet |
| `rename_sheet` | Rename a sheet |
| `copy_sheet` | Duplicate a sheet (drops charts/images) |
| `read_range` | Read cell values |
| `write_range` | Write cell values |
| `append_rows` | Append rows below last data |
| `clear_range` | Clear values, preserve formatting |
| `read_format` | Read cell formatting (colors, bold, borders) |
| `format_range` | Apply formatting to a range |
| `set_column_width` | Set column widths |
| `set_row_height` | Set row heights |
| `merge_cells` | Merge a cell range |
| `unmerge_cells` | Unmerge a cell range |
| `create_chart` | Create a bar, line, pie, or scatter chart |
| `write_formula` | Write a formula to a single cell |

## Troubleshooting

**MCP server won't start / tool not found:**
Claude Desktop launches MCP servers as background processes with no visible output.
To see server logs, run the server manually:
```bash
xlsx-drive-mcp --user your@email.com
```
Any errors will appear in the terminal.

**`list_xlsx_files` returns no results:**
With `drive.file` scope, only files this app created or previously opened are visible.
Use `get_xlsx_info(file_id)` directly with a known `file_id` from the Drive URL instead.

**Shared Drive / Team Drive:**
Not officially tested in v1. May work; not supported. Open an issue if you test it.

**Service accounts:**
Not supported in v1. Tracked as a roadmap item.

## License

MIT