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., "@mcp-server-xlwings Summarize the data I've selected"
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.
MCP server for Excel automation via xlwings COM. Works with DRM-protected files.
Libraries like openpyxl or pandas read .xlsx files directly from disk. This fails when:
DRM / file-level encryption is applied (common in enterprise environments)
You need to interact with a live Excel session (formulas, macros, add-ins)
Files are locked by another process
mcp-server-xlwings uses COM automation to talk to the running Excel process, so it can read and write any file that Excel itself can open -- including DRM-protected documents.
These features are impossible with file-based libraries like openpyxl:
Read the user's current selection -- see exactly what the user is looking at
Get the active workbook -- no need to specify a file path
Run VBA macros -- execute existing macros and get their return values
Live formula results -- set a formula and get the calculated value immediately
Force recalculation -- trigger Excel to recalculate all formulas
Related MCP server: Excel MCP Server
uvx mcp-server-xlwingspip install mcp-server-xlwingsAdd to %APPDATA%\Claude\claude_desktop_config.json:
{
"mcpServers": {
"xlwings": {
"command": "uvx",
"args": ["mcp-server-xlwings"]
}
}
}claude mcp add xlwings -- uvx mcp-server-xlwingsAdd to Roo Code MCP settings or create <project-root>/.roo/mcp.json:
{
"mcpServers": {
"xlwings": {
"command": "uvx",
"args": ["mcp-server-xlwings"]
}
}
}Add to %USERPROFILE%\.cursor\mcp.json:
{
"mcpServers": {
"xlwings": {
"command": "uvx",
"args": ["mcp-server-xlwings"]
}
}
}Add to %USERPROFILE%\.codeium\windsurf\mcp_config.json:
{
"mcpServers": {
"xlwings": {
"command": "uvx",
"args": ["mcp-server-xlwings"]
}
}
}Add to ~/.continue/config.yaml:
mcpServers:
- name: xlwings
command: uvx
args:
- mcp-server-xlwingsAll tools default to the active workbook when workbook is omitted.
Tool | Description |
| Get active workbook info, sheets, and current selection with data |
| List, open, save, close, or recalculate workbooks |
| Read a range with |
| Write a 2D array ( |
| List, add, delete, rename, copy, activate sheets. Insert/delete rows and columns |
| Search for text, optionally replace it |
| Apply formatting (bold, italic, color, borders, alignment, number format, etc.) |
| Execute a VBA macro and get its return value |
| Get all formulas in a range with optional calculated values |
| Get formatting/style info (bold, colors, borders, etc.) for cells in a range |
| List charts, images, and shapes on a sheet |
"What's in the spreadsheet I have open?"
The agent calls get_active_workbook() to get the workbook name, sheets, and selection data, then read_data() to fetch the full sheet.
"Summarize the data I've selected"
The agent calls get_active_workbook() -- the response includes the selection data directly.
"Run the UpdateReport macro"
The agent calls run_macro(macro_name="UpdateReport") and returns the result.
"Add a SUM formula in C10 that totals C2:C9"
The agent calls write_data(start_cell="C10", formula="=SUM(C2:C9)") and gets back the calculated value.
"Make row 1 bold and centered with a yellow background"
The agent calls format_range(cell_range="A1:D1", bold=true, alignment="center", bg_color="#FFFF00").
"Give me a summary of every sheet"
The agent calls read_data(sheet="*") -- returns all sheet summaries in a single call.
"Read B6:C20 and fill in merged cell values"
The agent calls read_data(cell_range="B6:C20", merge_info=true). Merged cells return the parent value instead of null.
"Show me all formulas in this sheet"
The agent calls get_formulas(cell_range="A1:Z100", values_too=true) and gets every formula with its calculated value.
"Insert 3 blank rows at row 5"
The agent calls manage_sheets(action="insert_rows", position=5, count=3).
Windows (Excel COM automation is Windows-only)
Microsoft Excel installed
Python 3.10+
MIT
Search for text in a sheet, optionally replacing it.
Args: find: Text to search for. workbook: Workbook name or path. Defaults to active workbook. sheet: Sheet name. Defaults to active sheet. replace: Replacement text. If omitted, search only. match_case: Case-sensitive matching.
| Name | Required | Description | Default |
|---|---|---|---|
| find | Yes | ||
| workbook | No | ||
| sheet | No | ||
| replace | No | ||
| match_case | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=false, and the description clarifies that replacement is optional. However, it does not explain whether replacements are global or per-occurrence, or what the return value is, leaving behavior somewhat ambiguous.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single introductory sentence followed by a bullet-like list of parameters. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks information about return values (e.g., count of matches/replacements) and does not specify search behavior (e.g., regex vs. plain text). Given the tool's complexity and lack of output schema, this is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions (0% coverage), but the description provides brief explanations for all five parameters, including defaults and behavior (e.g., match_case for case-sensitivity). This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for text in a sheet and optionally replaces it. This distinguishes it from sibling tools like read_data, write_data, and format_range, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
While the description indicates that replacement is optional, it provides no explicit guidance on when to use this tool versus alternatives (e.g., read_data for reading only) or any prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply formatting to a cell range.
Args: cell_range: Range like 'A1:D10'. workbook: Workbook name or path. Defaults to active workbook. sheet: Sheet name. Defaults to active sheet. bold: Set bold. italic: Set italic. underline: Set underline. font_size: Font size in points. font_color: Hex colour like '#FF0000'. bg_color: Background hex colour like '#FFFF00'. number_format: Excel format like '#,##0.00'. alignment: 'left', 'center', 'right', 'justify'. wrap_text: Enable text wrapping. border: Apply thin borders.
| Name | Required | Description | Default |
|---|---|---|---|
| cell_range | Yes | ||
| workbook | No | ||
| sheet | No | ||
| bold | No | ||
| italic | No | ||
| underline | No | ||
| font_size | No | ||
| font_color | No | ||
| bg_color | No | ||
| number_format | No | ||
| alignment | No | ||
| wrap_text | No | ||
| border | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include destructiveHint: true, but the description adds no behavioral context beyond listing parameters. It does not disclose that formatting overrides existing styles, that it may be irreversible, or any auth/rate-limit requirements. The description adds minimal value over the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a focused bullet list, each line covering one parameter with a brief explanation. No redundant sentences, though some entries are minimal. Well-structured for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 13 parameters, no output schema, and no return value documentation, the description is incomplete. It does not explain what happens after formatting (e.g., success/error), behavior with partial parameter sets, or how defaults are applied. The high complexity warrants more coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It provides examples (e.g., hex colors, number format like '#,##0.00') and explains alignment values. However, many parameters like 'bold' or 'italic' are just restated from the schema with 'Set bold/italic' offering no additional semantic depth. Overall, it adds some but not full compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Apply formatting' and the resource 'cell range', with a comprehensive list of formatting options. It distinguishes from sibling tools like 'write_data' (value writing) and 'read_data' (reading values) by focusing on formatting only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for formatting a range but provides no explicit guidelines on when to use this tool versus alternatives like 'get_cell_styles' (reading styles) or 'find_replace'. No when-not-to-use or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the currently active workbook info including sheets, active sheet, and current selection address with its data.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. The description adds context by listing the returned info (sheets, active sheet, selection address with data), which is useful beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with purpose, no wasted words. Highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter tool without output schema, the description adequately covers the return contents (sheets, active sheet, selection address with data). No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. The schema coverage is 100% and no additional parameter info is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves active workbook info including sheets, active sheet, and current selection data. It is a specific verb+resource and distinguishes from siblings like read_data or manage_workbooks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied but no explicit when-to-use or alternative guidance is provided. For a simple tool, this is adequate but lacks explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get formatting/style info for cells in a range. Returns only cells with non-default styles. Useful for identifying headers, subtotals, and data roles by visual formatting.
Args: cell_range: Range like 'A1:D10'. workbook: Workbook name or path. Defaults to active workbook. sheet: Sheet name. Defaults to active sheet. properties: Filter specific properties (bold, italic, underline, font_name, font_size, font_color, bg_color, number_format, alignment, border).
| Name | Required | Description | Default |
|---|---|---|---|
| cell_range | Yes | ||
| workbook | No | ||
| sheet | No | ||
| properties | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation indicates readOnlyHint=true, and the description adds behavioral context such as returning only non-default styles and listing filterable properties. However, it does not mention output format or error handling, and the description adds moderate value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, starts with the main purpose, adds a key behavioral trait, and then lists parameters in a well-structured Args section with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, parameter explanations, and use cases, but lacks details about the output format and error handling, which is a gap given the absence of an output schema and the moderate complexity of four parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining each parameter: cell_range with example, workbook and sheet with defaults, and properties with a list of possible values, adding significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get formatting/style info for cells in a range' and specifies that it returns only cells with non-default styles, distinguishing it from sibling tools like format_range (which modifies styles) and read_data (which reads values).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes it is 'useful for identifying headers, subtotals, and data roles by visual formatting,' providing clear context for usage, but does not explicitly exclude alternatives or compare with siblings like format_range.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all formulas in a range. Returns only cells that contain formulas.
Args: cell_range: Range like 'A1:U99'. workbook: Workbook name or path. Defaults to active workbook. sheet: Sheet name. Defaults to active sheet. values_too: Include calculated values alongside formulas.
| Name | Required | Description | Default |
|---|---|---|---|
| cell_range | Yes | ||
| workbook | No | ||
| sheet | No | ||
| values_too | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint=true, and the description goes beyond by explaining that only formula cells are returned and that values_too includes calculated values. This adds context about the tool's behavior without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear header and bullet-pointed arguments. Every sentence is informative, no redundancy, and the main purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with 4 parameters and no output schema, the description covers purpose, parameters, and defaults. It could mention return format or behavior when no formulas exist, but overall is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully documents each parameter: cell_range ('Range like A1:U99'), workbook (name/path, defaults to active), sheet (defaults to active), values_too (include values). This adds meaningful details beyond the schema's type-only definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get all formulas in a range. Returns only cells that contain formulas.' This uses a specific verb and resource, and distinguishes itself from sibling tools like read_data (which returns all values) and find_replace (which modifies).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through 'Returns only cells that contain formulas,' suggesting use when formulas are needed versus values. However, no explicit when/when-not or alternatives are mentioned, missing opportunities to differentiate from read_data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List charts, images, and shapes on a sheet.
Args: workbook: Workbook name or path. Defaults to active workbook. sheet: Sheet name. Defaults to active sheet.
| Name | Required | Description | Default |
|---|---|---|---|
| workbook | No | ||
| sheet | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already marks this as a read operation. The description adds value by specifying the exact object types (charts, images, shapes) beyond the annotation's generic 'read only' label. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is minimal and front-loaded: one sentence for purpose, followed by parameter docs. No wasted words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks details about the return format (e.g., IDs, names, positions). While it implies listing objects, the absence of an output schema means the agent must infer what data is returned. For a simple list operation with 0 required params, this is a moderate gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by clearly defining both parameters: workbook and sheet names with defaults ('active workbook/sheet'). This adds meaning beyond the schema's type and default fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool lists 'charts, images, and shapes on a sheet,' with a clear verb ('list') and resource. This distinguishes it from siblings like read_data or get_cell_styles, which focus on cell content rather than graphical objects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or scenarios where another sibling tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage sheets and structure.
Args: action: One of 'list', 'add', 'delete', 'rename', 'copy', 'activate', 'insert_rows', 'delete_rows', 'insert_columns', 'delete_columns'. workbook: Workbook name or path. Defaults to active workbook. sheet: Target sheet name (required for delete/rename/copy/activate). new_name: New name (for rename; optional for add/copy). position: Row/column number (1-based) for insert/delete actions. count: Number of rows/columns to insert or delete.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| workbook | No | ||
| sheet | No | ||
| new_name | No | ||
| position | No | ||
| count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations set destructiveHint: true, and the description includes actions like delete, which implies destructive behavior. The description does not elaborate on side effects, permissions, or reversibility beyond what annotations provide, but it does not contradict them either.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a brief overview followed by a bullet list of parameters. While somewhat lengthy, every sentence serves a purpose and the format is clear. Minor redundancy (e.g., actions listed twice) could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all parameters and their roles but does not explain return values or behavior for each action (e.g., what 'list' returns). Given no output schema, this gap reduces completeness for an agent invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description fully explains each parameter: action lists valid options, workbook defaults to active, sheet is required for specific actions, new_name for rename/add/copy, position and count for insert/delete. This adds essential meaning missing from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Manage sheets and structure' and lists specific actions via the action parameter. While it clearly indicates the tool's purpose for sheet-level operations, it does not explicitly differentiate from sibling tools like manage_workbooks, but the action list implicitly covers that.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., manage_workbooks for workbook operations, write_data for data changes). The description does not include any when-to-use or when-not-to-use information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage Excel workbooks: list, open, save, close, or recalculate.
Args: action: One of 'list', 'open', 'save', 'close', 'recalculate'. workbook: Workbook name or path. Defaults to active workbook. filepath: For 'open': file path (use 'new' for blank). For 'save': Save As path. read_only: For 'open': open in read-only mode. save: For 'close': save before closing.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| workbook | No | ||
| filepath | No | ||
| read_only | No | ||
| save | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lists actions but does not disclose behavioral traits beyond the annotations' destructiveHint. It lacks details on side effects (e.g., saving overwrites, closing may lose changes, recalculating is time-consuming) or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a one-line summary followed by argument explanations. Every sentence provides unique value, and the structure is front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple actions, 5 parameters), the description covers parameter semantics well. However, it omits return behavior and error conditions. For a tool without output schema, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description fully compensates by explaining each parameter's purpose, especially the 'action' parameter with specific allowed values, and how other parameters relate to actions (e.g., filepath for open/save, read_only for open).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it manages Excel workbooks and lists specific actions (list, open, save, close, recalculate). While it distinguishes from siblings like 'manage_sheets' by focusing on workbooks, it does not explicitly contrast with all sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention when not to use it or suggest specific sibling tools for other tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read data from an Excel range. When cell_range is omitted, returns a sheet summary (used range address, total rows/columns, headers) WITHOUT reading all data -- call again with a specific cell_range to fetch the actual data. Set detail=True on a single cell to get formula, type, and formatting info. Use sheet="*" to batch-read all sheets in one call.
Args: workbook: Workbook name or path. Defaults to active workbook. sheet: Sheet name. Defaults to active sheet. Use '*' to read all sheets. cell_range: Range like 'A1:D10' or cell like 'B5'. Returns sheet summary if omitted. headers: Treat first row as column headers. detail: For single cells, include formula, type, number format, and font info. merge_info: Fill merged cells with the merge area's value instead of null. header_row: 1-based row number to use as headers (e.g. 3 means row 3 is headers).
| Name | Required | Description | Default |
|---|---|---|---|
| workbook | No | ||
| sheet | No | ||
| cell_range | No | ||
| headers | No | ||
| detail | No | ||
| merge_info | No | ||
| header_row | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors beyond the readOnlyHint annotation: returning a summary when cell_range is omitted, providing formula/format with detail=True, filling merged cells with merge_info, and batch-reading with sheet='*'. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a main statement followed by special behaviors and an Args list. It is slightly verbose but front-loaded with the core action, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains return values: sheet summary (used range, total rows/columns, headers) when cell_range omitted, and detailed info (formula, type, formatting) when detail=True. It also covers merge_info behavior, making it complete for a read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description's Args section explains all 7 parameters in detail: workbook (name/path), sheet (name or '*'), cell_range (range or cell, omission behavior), headers, detail, merge_info, and header_row. This fully compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads data from an Excel range, with specific variations for when cell_range is omitted (sheet summary) or detail=True (single cell info). It differentiates from siblings like write_data, format_range, and get_formulas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to omit cell_range for summary, use detail for single-cell data, and use sheet='*' for all sheets. However, it lacks explicit when-not-to-use instructions or comparisons with alternatives like format_range or get_cell_styles.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a VBA macro in Excel and return its result.
Args: macro_name: Macro name (e.g. 'MyMacro' or 'Module1.MyMacro'). workbook: Workbook name. If omitted, Excel resolves globally. args: Optional arguments to pass to the macro.
| Name | Required | Description | Default |
|---|---|---|---|
| macro_name | Yes | ||
| workbook | No | ||
| args | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, indicating potential destructive behavior. Description adds that it returns a result, but does not detail the result format, error handling, or side effects beyond annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, well-structured with a clear purpose sentence and list of parameters. No extraneous information, front-loaded with core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing details on return value type, error cases (e.g., macro not found), and permission requirements. With no output schema, more context on the result would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description adds meaning by providing examples for macro_name, explaining workbook optionality and global resolution, and noting args are optional. Compensates for the schema gap, but could specify argument type constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it runs a VBA macro and returns its result, with specific examples for parameters. This distinguishes it from siblings like read_data or manage_sheets, which handle other Excel operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, such as when to run a macro versus directly modifying data with other tools. Lack of context for selecting this tool among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write data or a formula to Excel cells. Provide 'data' for a 2D array, or 'formula' for a single-cell formula.
Args: start_cell: Top-left cell (e.g. 'A1'). data: 2D list of values. Mutually exclusive with formula. formula: Excel formula like '=SUM(A1:A10)'. Mutually exclusive with data. workbook: Workbook name or path. Defaults to active workbook. sheet: Sheet name. Defaults to active sheet.
| Name | Required | Description | Default |
|---|---|---|---|
| start_cell | Yes | ||
| data | No | ||
| formula | No | ||
| workbook | No | ||
| sheet | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already give destructiveHint=true, indicating mutation. Description adds that it writes to cells and the mutual exclusivity of parameters, but does not detail whether it overwrites existing content or other behavioral nuances.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with a brief introductory sentence followed by a clear Args list. It is front-loaded and efficient, though it could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a write tool with destructiveHint, but lacks information about return values or error handling. Without an output schema, the agent does not know what to expect after writing (e.g., success flag, modified range).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description fully explains all five parameters: start_cell, data (2D list), formula (Excel formula), workbook, and sheet, including mutual exclusivity. This adds substantial meaning beyond the schema's type-only definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Write data or a formula to Excel cells' with a specific verb and resource. Distinguishes between writing data (2D array) and a single-cell formula, and contrasts with sibling read_data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear instructions: use 'data' for a 2D array or 'formula' for a single-cell formula, and notes mutual exclusivity. However, does not explicitly advise when to use this tool versus alternatives like format_range or find_replace.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.4.1find_replaceformat_rangeget_active_workbookget_cell_stylesget_formulasget_objectsmanage_sheetsmanage_workbooksread_datarun_macrowrite_dataScored across 11 tools
Each tool targets a distinct operation: read, write, format, find/replace, manage sheets/workbooks, run macros, retrieve formulas/styles/objects, and get active workbook info. No overlapping purposes; descriptions clearly differentiate them.
All tools follow the verb_noun pattern with underscores (e.g., find_replace, get_cell_styles). Verbs are imperative and consistent throughout, making the naming predictable and easy to understand.
With 11 tools, the server covers core Excel interactions without excess. It provides enough functionality to automate common tasks without overwhelming the agent with too many choices.
The tool surface covers reading, writing, formatting, finding, managing structure, running macros, and inspecting styles/objects. Minor gaps exist, such as creating charts or pivot tables, but the set is sufficient for typical data manipulation and formatting workflows.
Excel analytics: inspect, query (JSON rows), charts, and JSON-to-xlsx workbook writing.
Real Word and Excel for agents: open your .docx/.xlsm, read, propose, apply, get it back intact.
AI access to Quadratic spreadsheets: open files, run Python/SQL, query connected databases.
Formula-backed WorkPaper tools for workbook readback, input edits, and JSON persistence.
