XLSafe
README.md
# XLSafe
A Windows desktop app that lets Claude (or any MCP client) read and edit your Excel files without touching the originals. It wraps [negokaz/excel-mcp-server](https://github.com/negokaz/excel-mcp-server) and adds:
- **Folder sandbox.** You pick one or more folders. Claude can only see Excel files (`.xlsx .xlsm .xltx .xltm`) inside them.
- **Edits go to temporary copies.** Claude never writes your file. Each edited file gets a private working copy.
- **Your approval.** A pop-up asks before Claude can edit a file. You can allow one file, allow all files for this session, or deny.
- **Review, then apply.** A cell-by-cell "what changed" view. Your file only changes when you click **Apply**.
- **Last 3 backups of every file.** Every apply or restore backs up the previous version first. The 3 newest backups per file are kept.
- **Secure link.** A Cloudflare or Tailscale tunnel gives Claude an HTTPS link to your PC. No ports are opened, and the link contains a secret.
XLSafe is free and open source (MIT). It is not affiliated with Anthropic, Microsoft, Cloudflare or Tailscale.
**[Download the latest release](https://github.com/Diwanshumidha/xlsafe/releases/latest)** · [Privacy policy](PRIVACY.md) · [Code signing policy](#code-signing-policy)
## For end users
1. From the [latest release](https://github.com/Diwanshumidha/xlsafe/releases/latest), download and run `XLSafe-Setup-x.y.z.exe` (installs XLSafe with an uninstaller), or `XLSafe-x.y.z-portable.exe` to run it without installing.
*Until releases are code-signed, Windows may show "Windows protected your PC". Click **More info → Run anyway**.*
2. The setup wizard asks for your Excel folder and connection type. Choose **Quick link** if unsure.
3. Click **Start sharing**, then **Copy link**.
4. In Claude: **Settings → Connectors → Add custom connector**. Name it *Excel*, paste the link, and save.
5. In a chat, turn on the Excel connector and ask, e.g. *"Add a totals row to Finance/Q3 Budget.xlsx"*.
6. Approve the pop-up when Claude wants to edit.
7. Go to **Review changes → See what changed → Apply to my file** (or **Discard**).
8. To undo an apply, go to **Backups → Restore**.
With a Quick link, the link changes every time you start sharing, so update the connector each time. For a permanent link, use Tailscale (free) or Cloudflare with your own domain (see below).
Requirements: Windows 10 or 11 (64-bit), and a Claude plan that supports custom connectors.
## How it works
```
Claude ──HTTPS──► Cloudflare tunnel ──► 127.0.0.1:47821/mcp/<secret> (XLSafe, Electron main process)
│ checks: secret, expiry, rate limit, body size, origin
│ tool layer: path sandbox → approval → working copy
▼ stdio
excel-mcp-server.exe ──► %LOCALAPPDATA%\XLSafe\work\copies\<id>\file.xlsx
```
| Tool exposed to the AI | What it does |
|---|---|
| `list_excel_files(folder?)` | Excel files in the shared folders, as paths like `Finance/2026/budget.xlsx` |
| `request_edit_access(file, reason)` | Shows the approval pop-up |
| `fill_formula(file, sheetName, range, formula)` | Fill one formula down or across a range like Excel's fill handle, expanded locally (up to 200,000 cells per call). Needs approval |
| `get_status()` | Which files are approved and which have pending edits |
| `describe_sheets`, `read_sheet` | Read. Uses the working copy if one exists, otherwise a read-only snapshot |
| `write_to_sheet`, `format_range`, `create_table`, `copy_sheet` | Edit the working copy. Needs approval |
The upstream tools take a `fileAbsolutePath`. XLSafe removes that parameter from what the AI sees and always injects the working-copy path itself. Any path the AI sends is ignored.
## Security model
| Threat | Mitigation |
|---|---|
| AI reads or writes arbitrary files | Paths are resolved against the shared folders only. `..`, drive letters, UNC, ADS (`:`), reserved names and hidden or `~$` files are rejected. Real paths are re-checked after `realpath`, so symlinks and junctions can't escape. Size limit applies. |
| AI damages the original | Edits only go to working copies stored outside the shared folders. Originals change only when the user applies. |
| Lost work | The previous version is backed up before every apply or restore (newest 3 kept). Apply refuses if the original changed since the copy was taken (the user can override). Replacement is atomic (temp file + rename). |
| Someone else uses the link | 256-bit secret in the URL path, compared in constant time. Wrong secrets get 404, and 20 failures in 10 minutes from one IP get 429. Sharing stops automatically (30 min to 8 h). "Create a new secret link" revokes the old one. |
| Network exposure | The server binds to `127.0.0.1` only. External access is only through the tunnel. |
| Browser-based attacks | Requests with a non-local `Origin` header are refused. |
| Secrets on disk | The link secret and Cloudflare token are encrypted with Windows DPAPI (Electron `safeStorage`). |
| Leaking disk layout to the AI | Tool output is scrubbed of real paths. |
| Malicious content in the UI | Electron: `contextIsolation`, `sandbox`, no `nodeIntegration`, strict CSP, no navigation or new windows, only `file://` loads. IPC is a fixed allowlist with sender checks. All AI or file data is rendered with `textContent`. |
| Overly broad sharing | Drive roots, the whole user profile, and Windows/Program Files/AppData folders can't be shared. Overlapping folders are rejected. |
| Audit | Every tool call, approval, apply, discard and restore is logged to `%LOCALAPPDATA%\XLSafe\logs\activity-YYYY-MM-DD.jsonl` (90 days kept). |
Approval pop-ups auto-deny after 30 to 90 seconds, because Cloudflare drops requests that take longer than 100 seconds.
## Permanent link with Tailscale (free, no domain needed)
1. Install Tailscale from https://tailscale.com/download/windows and sign in (a free personal account is fine).
2. In XLSafe, go to **Settings → Connection → Permanent link (Tailscale)** and click **Check Tailscale**. It shows your link, e.g. `https://my-pc.tail1234.ts.net/mcp/…`.
3. Click **Start sharing**. The first time, XLSafe may show a **Turn on Funnel** button. Click it, approve in the browser, then click **Start sharing** again.
4. Add the link to Claude once. It stays the same every time you share, until you click "Create a new secret link".
XLSafe runs `tailscale funnel` in foreground mode on port 443. The Funnel exists only while sharing is on and disappears if XLSafe exits or crashes. XLSafe refuses to start if you already have your own Funnel or serve set up on port 443.
## Permanent link with Cloudflare (for IT, needs a domain)
1. In Cloudflare Zero Trust, go to **Networks → Tunnels → Create tunnel (Cloudflared)**.
2. Add a public hostname, e.g. `excel.yourcompany.com`, pointing to service `http://localhost:47821`.
3. Copy the tunnel token. In XLSafe, go to **Settings → Connection → Stable link**, then paste the hostname and token.
4. The connector link is then always `https://excel.yourcompany.com/mcp/<secret>`.
## Large files
Tested with 100,000 rows × 10 columns (5 MB): every operation takes 3 to 14 seconds (well under the tunnel's 100-second limit), including filling a formula into all 100,000 rows. The Review-page diff streams through the files (about 4 s, under 500 MB peak with 100k changed cells). Claude reads large sheets in pages of 4,000 cells and is told to use formulas and `fill_formula` rather than reading or writing every row.
## Patched excel-mcp-server
XLSafe ships its own build of excel-mcp-server v0.12.0 with `third_party/excel-mcp-server/xlsafe-no-ole.patch` applied:
- **No attaching to the user's running Excel.** Upstream tries OLE on every call: it sets `ScreenUpdating`/`EnableEvents` off on whatever Excel is open, and doesn't restore them when the workbook isn't there (which is always the case for XLSafe's private copies). The user's Excel then shows a blank window and won't open files until it's killed.
- **`screen_capture` removed.** It starts a hidden Excel and never quits it (upstream calls `Application.Close`, which doesn't exist). That orphan then grabs files the user double-clicks. XLSafe's tool layer also blocks this tool.
- **No crash on sheets without a sheet-view section.** Files not saved by Excel often lack `<sheetViews>`, and excelize's copy/move sheet crashed on them. Every sheet now gets the default view when the file is opened.
- **Formulas stored the way Excel stores them**, without a leading `=`.
- **Excel recalculates on open** (`fullCalcOnLoad`). The engine doesn't store formula results, so without this flag new formulas could show blank or 0 until F9.
- **Missing used range rebuilt.** Files from streaming exporters often omit `<dimension>`; reads then failed with "no range available". It's recomputed when the file is opened.
- **Write echo capped at 100 rows.** Echoing a 100,000-row write produced a reply over the 10 MB MCP message limit.
`npm run build-excel-server` clones the pinned upstream commit, verifies it, applies the patch, and builds `vendor/win/excel-mcp-server.exe` (plus the host OS). It needs Go 1.23 or newer.
## Development
```bash
npm install
npm test # builds, then end-to-end tests (real excel-mcp-server + HTTP + MCP client)
npm start # run the app
npm run dist:win # on Windows: installer + portable exe into release/ (what CI runs)
npm run dist:win:local # on Linux/macOS: portable exe only, without exe metadata or icon
```
- The installer and exe metadata need Windows (or Wine), so releases are built by `.github/workflows/build-windows.yml` on a Windows runner. Pushing a `v*` tag builds, tests, signs (once SignPath is set up) and publishes a GitHub Release.
- `scripts/fetch-cloudflared.mjs` downloads a pinned `cloudflared.exe` and verifies its SHA-256.
- Dev-only environment variables (ignored in packaged builds): `XLSAFE_DATA_DIR` (alternate data folder) and `XLSAFE_SMOKE=<dir>` (screenshot every page offscreen, then quit).
Data lives in `%LOCALAPPDATA%\XLSafe\`: `settings.json`, `work\` (working copies + read snapshots), `backups\` (3 per file), `logs\`.
## Layout
```
src/core/ Electron-free logic (testable headless)
fsguard.ts folder sandbox / path validation
workspace.ts working copies, apply / discard
backups.ts keep-last-3 backup store, restore
tools.ts AI-facing tools, approval gating, output scrubbing
server.ts Streamable HTTP MCP endpoint (auth, limits)
tunnel.ts cloudflared quick / named tunnel
upstream.ts excel-mcp-server over stdio
diff.ts cell-level diff (exceljs)
engine.ts orchestration
src/main/ Electron main process, approval dialog, IPC, preload
src/renderer/ GUI (plain HTML/CSS/JS)
test/ end-to-end tests
```
## Code signing policy
Free code signing provided by [SignPath.io](https://about.signpath.io), certificate by [SignPath Foundation](https://signpath.org).
Signed files show **SignPath Foundation** as the publisher. Only `XLSafe-Setup-*.exe` and `XLSafe-*-portable.exe`, built by this repository's [GitHub Actions workflow](.github/workflows/build-windows.yml) from a tagged commit, are signed. Third-party binaries inside the package (`excel-mcp-server.exe`, `cloudflared.exe`) are not signed by this project; see [third_party/NOTICE.md](third_party/NOTICE.md).
Team roles:
- Committers and reviewers: [Diwanshu (@Diwanshumidha)](https://github.com/Diwanshumidha)
- Approvers: [Diwanshu (@Diwanshumidha)](https://github.com/Diwanshumidha)
Every signing request is approved manually by an approver.
## Privacy
XLSafe has no accounts, telemetry or analytics. It sends file contents only while you're sharing, only to the AI assistant you connect, and only through the connection you choose. Read the full [privacy policy](PRIVACY.md), which is also shown in the app during setup.
## Contributing
Issues and pull requests are welcome. Run `npm test` before submitting. Changes to build scripts and CI are reviewed like any other code, since they produce the signed releases.
To report a security problem, please use [GitHub's private vulnerability reporting](https://github.com/Diwanshumidha/xlsafe/security/advisories/new) instead of a public issue.
## License
[MIT](LICENSE) © 2026 Diwanshu. Bundled third-party software keeps its own licenses; see [third_party/NOTICE.md](third_party/NOTICE.md).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues