A
licenseNot graded
qualityD
maintenanceEnables interaction with SharePoint Online and OneDrive content via Microsoft Graph, supporting device-code authentication for multi-account environments.
1
MIT
graph-excel-mcp
by mickey-ichi
This MCP server lets AI agents read and edit Excel workbooks on SharePoint, OneDrive, or Teams through Microsoft Graph, with dry runs, conflict checks, and read-back verification.
Sign in with a device code and check Microsoft Graph authentication status.
Resolve workbook URLs, aliases, or
driveId:itemIdreferences and list sheets with used ranges.Read ranges with per-cell SHA-256 hashes, optional fill colors, and hash-only output.
Write cell values in blocks with expected-content/hash checks, conflict skipping, and verification.
Append or replace
-----update-----sections under existing cell text while preserving the original content, with optional fill color.Set or clear fill colors for one or more ranges.
Search cell text across all sheets or one sheet using substring or regex matching, with hashes and limits.
Add new worksheets or rename existing sheets.
Insert empty rows above a row or append rows below the last used row, with verification.
Apply formatting such as bold, italic, font color/size, wrap text, alignment, and number formats.
Default every mutating operation to a dry run until
send: true; never delete sheets, rows, or cells.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@graph-excel-mcp update the Q3 budget totals in the Finance workbook and verify the cells"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
graph-excel-mcp
Read and edit Excel workbooks on SharePoint and OneDrive from AI agents — without overwriting anyone’s edits.
npm · Claude Desktop extension · Releases
MCP server for reading and editing Excel workbooks on SharePoint, OneDrive or Teams through Microsoft Graph, without a browser. It is written in TypeScript, has no runtime dependencies, and runs on Node 18 or later.
It is built for workbooks that several people edit at once:
Every write starts as a dry run.
Before writing, it checks the cells' current content against the version you read, so it won't overwrite someone else's edit.
After writing, it reads the cells back to confirm the change.
Install
Claude Code / any MCP host (stdio):
claude mcp add --scope user graph-excel -- npx -y graph-excel-mcp{ "mcpServers": { "graph-excel": { "command": "npx", "args": ["-y", "graph-excel-mcp"] } } }Claude Desktop extension: download graph-excel-mcp-<version>.mcpb from the latest release and open it. One install covers both Chat and Cowork in Claude Desktop.
Claude plugin (Cowork, Claude Code): install the plugin/ folder of this repo. It contains the server and a graph-excel skill.
Related MCP server: excel-o365
Sign in
Call the login_status tool, or run npx graph-excel-mcp login, then enter the code it shows at https://login.microsoft.com/device. The refresh token is saved in ~/.graph-excel/token.json with mode 600. Set GRAPH_EXCEL_HOME to keep it somewhere else.
Sign-in uses the Microsoft Graph PowerShell public client with the delegated scope Files.ReadWrite.All, so you don't need to register an app. If your tenant blocks user consent, an admin has to approve that client once.
Workbook aliases
Instead of pasting the SharePoint URL every time, you can add aliases to ~/.graph-excel/workbooks.json (see workbooks.example.json). The resolve tool returns the driveId and itemId you need for an alias.
Tools
Tool | What it does |
| Checks the token, or starts a device code login |
| Returns drive/item ids, last modified, and the sheets with their used ranges |
| Returns values plus a |
| Writes blocks of values with a base check ( |
| Adds or replaces a 「-----update-----」 section under a cell's existing text, keeping the original part byte-identical, and can fill the row with a color |
| Sets or clears the fill color of one or more ranges in a single batch |
| Searches cell text across all sheets (or one), substring or regex, and returns addresses with hashes |
| Adds an empty sheet (Excel name rules, no duplicates), optionally at a position |
| Renames a sheet |
| Inserts empty rows above a row and verifies the shifted row moved intact |
| Appends rows below the last used row; the target cells must still be empty |
| Bold, italic, font color and size, wrap, alignment and number format for one or more ranges |
Every tool that changes the workbook is a dry run until send: true. Nothing deletes sheets, rows or cells.
Notes
Every call runs inside a workbook session. Sessionless calls on large workbooks can time out with a 504 even though the write was applied.
Line breaks are sent as
\n, which Excel stores as\r\n. If you write\r\ndirectly, the cell ends up with a stray_x000D_.
Development
Development needs Node 22.18 or later, which runs the .ts sources directly.
Command | What it does |
| Runs the server or the terminal sign-in from |
| Runs |
| Runs offline tests: range parsing, update composition, and the MCP handshake on |
| Compiles |
| Builds, then writes |
Layout:
Path | Contents |
| Auth and the Graph client |
| Workbook operations |
| Tools and the JSON-RPC server |
| Entry point |
Release
Bump version in package.json, run npm run pack, commit, then push a matching tag:
git tag v0.3.1 && git push origin v0.3.1The Publish workflow runs the tests, publishes to npm through trusted publishing (no token or OTP; provenance attached) and creates a GitHub release with the .mcpb attached.
Privacy
graph-excel-mcp has no server of its own and collects nothing. It signs in to Microsoft with a device code and keeps
the refresh token only in ~/.graph-excel/token.json (mode 600) on your computer. It talks to Microsoft only —
login.microsoftonline.com to sign in and graph.microsoft.com to read and write the workbooks you point it at.
Cell contents go to Claude only when you ask for them, and are then handled under your Claude plan's terms. No
telemetry, no third-party services.
Support
If graph-excel-mcp saves you time, you can support its development through GitHub Sponsors. Bug reports and pull requests are just as welcome.
License
MIT
Available Tools
12 toolsadd_sheetA
Add an empty worksheet (Excel name rules, no duplicate names), optionally at position (0 = first). Verified by listing the sheets afterwards.
Inputs: file (required), name (required), send, position.
append_rowsA
Append rows below the last used row of a sheet, starting at column (default A). values is a 2D array, one array per row. Base check: the target cells must still be empty; read back and verified like write_values.
Inputs: file (required), sheet (required), values (required), send, +1 more.
append_updateADestructive
Write the 「-----update-----」 part of cells in one row (e.g. H/I/J) and keep the original part byte-identical. No separator yet: appends blank line + separator + text. Separator present: mode=replace (default) swaps the update part, mode=append adds after it. Pass expected per column (sha256 from read_range) as the base check. After writing it verifies the original part is intact, then fills fillRange (default the updated columns of that row) with fill (default #FFFF00; null = no fill).
Inputs: row (required), file (required), sheet (required), update (required), +5 more.
findARead-only
Search cell text across every sheet (or one sheet): case-insensitive substring by default, regex=true for a JavaScript regular expression. Returns sheet, address, a preview and the sha256 hash per hit (≤ limit, default 50, max 500).
Inputs: file (required), text (required), limit, regex, +2 more.
insert_rowsA
Insert count empty rows above row; everything from row down shifts down. The dry run shows the row that will move. Verified afterwards: that row is found at row+count and the new rows are empty.
Inputs: row (required), file (required), sheet (required), send, +1 more.
login_statusARead-only
Check the Microsoft Graph sign-in. If not signed in, starts a device code login and returns the URL + code: give them to the user (never sign in for them), then call login_status again once they say they're done.
Inputs: no named parameters.
read_rangeARead-only
Read one contiguous range (e.g. H60:J60). Each cell comes with sha256: to pass back as expected when writing. fills=true adds each cell's fill color (≤400 cells). hashOnly=true omits the text (just hash + length).
Inputs: file (required), range (required), sheet (required), fills, +1 more.
rename_sheetADestructive
Rename a worksheet (Excel name rules, no duplicate names). Formulas that refer to it follow the new name. Verified by listing the sheets afterwards.
Inputs: file (required), sheet (required), newName (required), send.
resolveBRead-only
Workbook info: driveId/itemId, last modified (when/by whom), and every sheet with its used range.
Inputs: file (required).
set_fillADestructive
Set or clear the fill color of one or more contiguous ranges (non-contiguous rows = several ranges; sent in one batch). color "#FFFF00" etc., or null to clear. Verified by reading the fill back.
Inputs: file (required), sheet (required), ranges (required), send, +1 more.
set_formatADestructive
Format one or more contiguous ranges: bold, italic, fontColor (#RRGGBB), fontSize, wrapText, horizontalAlignment (General/Left/Center/Right/Justify), numberFormat (e.g. "yyyy-mm-dd", "0.00", "@" for text). Font changes are read back and verified. Fill colors: use set_fill.
Inputs: file (required), sheet (required), ranges (required), bold, +7 more.
write_valuesADestructive
Write blocks of cell values. Each block is one contiguous range with a 2D values array (a scalar for one cell). expected (same shape; exact text, sha256:, or null to skip a cell) is the base check: a block whose current content differs is skipped as a conflict, never half-written. After writing, every block is read back and compared (status written-verified / written-mismatch). Values are interpreted like typed input: text that looks like a number/date may be converted — mismatches report it.
Inputs: file (required), sheet (required), writes (required), send.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
A3.7/5.0
Scored across 12 tools
Disambiguation4/5
Most tools target a clear resource+action, and the descriptions explicitly separate overlapping areas (e.g. set_format says to use set_fill for colors). The main potential confusion is between write_values, append_update, and append_rows, but their descriptions make the boundaries reasonably clear.
Naming Consistency4/5
Nine of twelve tools follow a clear verb_noun pattern (read_range, write_values, add_sheet, insert_rows, set_format, etc.). The outliers are single verbs (resolve, find) and a noun phrase (login_status), which are minor deviations but still readable.
Tool Count5/5
Twelve tools is well-scoped for an Excel workbook server, covering authentication, discovery, read/write, search, sheet management, rows, fills, and formatting. Each tool earns its place without obvious redundancy.
Completeness3/5
The surface covers reading, writing, appending, searching, adding/renaming sheets, inserting/appending rows, fills, and formatting. However, there are notable lifecycle gaps: no delete_sheet, delete_rows, or clear-range operation, which are common spreadsheet tasks and hard to work around with the current tools.
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues
Related MCP Connectors
Excel analytics: inspect, query (JSON rows), charts, and JSON-to-xlsx workbook writing.
Manage Microsoft 365 email, calendar, contacts and inbox rules via the Graph API with OAuth 2.0.
Permissioned access to Outlook, OneDrive and Teams via the user's own Microsoft account
Formula-backed WorkPaper tools for workbook readback, input edits, and JSON persistence.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables managing Excel files in Microsoft 365 (OneDrive/SharePoint) through Microsoft Graph API, including creating workbooks, adding worksheets, creating tables, and reading or adding table rows via MCP tools.6Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents to edit real .xlsx workbooks in place through spreadsheet-native tools like describe, find, read, write, and structural edits, recalculating formulas without Excel, LibreOffice, or Python. Every change comes back as a review link showing changed cells before and after, and nothing is written until the user accepts, while charts, pivots, and VBA data return byte-identical.10Apache 2.0
- AlicenseAqualityBmaintenanceEnables building, editing, reading and converting spreadsheets through file-in/file-out tools, including live formulas, tables, conditional formatting, charts and PivotTables. Supports xlsx, csv, tsv, json, html and pdf input and output on Windows, macOS and Linux.9Apache 2.0