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

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, credentials are reused automatically. Skip to Claude Config below.

Option B: Standalone setup

1. Go to Google Cloud Console
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:

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

{
  "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:

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