> ## Documentation Index
> Fetch the complete documentation index at: https://prismeai-docs-next.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Excel

> Read and write Excel workbooks stored in OneDrive or SharePoint

The Excel connector provides full access to Microsoft Excel workbooks via the Microsoft Graph API, enabling AI agents and automations to read, write, and manipulate spreadsheets stored in OneDrive or SharePoint.

<CardGroup cols={3}>
  <Card title="Read & Write" icon="table">
    Access cell values, formulas, and ranges with full formatting support
  </Card>

  <Card title="Tables & Charts" icon="chart-bar">
    Create and manipulate Excel tables, charts, and pivot tables
  </Card>

  <Card title="Functions" icon="calculator">
    Execute Excel functions and recalculate workbooks
  </Card>
</CardGroup>

## Prerequisites

* An **Azure AD Application** registered in your tenant
* **Application permissions** granted:
  * `Files.Read.All` - Read-only access to files
  * `Files.ReadWrite.All` - Read/write access to files
  * `Sites.Read.All` or `Sites.ReadWrite.All` - For SharePoint-based files
* **Admin consent** granted for these permissions

***

<Tabs>
  <Tab title="Usage as App">
    ## Installation

    1. Go to **Apps** in your workspace
    2. Search for **Excel** and install it
    3. Configure the app instance with your Azure AD credentials

    ## Configuration

    | Field                   | Value                                 |
    | ----------------------- | ------------------------------------- |
    | **Azure Client ID**     | Application (client) ID from Azure AD |
    | **Azure Client Secret** | Client secret value                   |
    | **Azure Tenant ID**     | Directory (tenant) ID                 |
    | **SharePoint Site ID**  | Optional, for SharePoint-hosted files |

    ## File Access

    **OneDrive files** - provide only `itemId`:

    ```yaml theme={null}
    - Excel.getRange:
        itemId: "01ABCDEF..."
        worksheetId: Sheet1
        address: "A1:C10"
        output: data
    ```

    **SharePoint files** - provide `itemId` and `siteId`:

    ```yaml theme={null}
    - Excel.getRange:
        itemId: "01ABCDEF..."
        siteId: "contoso.sharepoint.com,abc-123,def-456"
        worksheetId: Sheet1
        address: "A1:C10"
        output: data
    ```

    ## Available Automations

    ### Workbook Operations

    | Automation          | Description                 |
    | ------------------- | --------------------------- |
    | `createWorkbook`    | Create a new Excel workbook |
    | `calculateWorkbook` | Recalculate all formulas    |

    ### Worksheet Operations

    | Automation        | Description               |
    | ----------------- | ------------------------- |
    | `listWorksheets`  | List all worksheets       |
    | `getWorksheet`    | Get worksheet details     |
    | `addWorksheet`    | Create new worksheet      |
    | `updateWorksheet` | Rename or reposition      |
    | `deleteWorksheet` | Delete worksheet          |
    | `getUsedRange`    | Get data-containing range |

    ### Range Operations

    | Automation     | Description                   |
    | -------------- | ----------------------------- |
    | `getRange`     | Read cell values and formulas |
    | `updateRange`  | Write values to cells         |
    | `getCell`      | Read a single cell            |
    | `clearRange`   | Clear contents or formatting  |
    | `insertRange`  | Insert cells with shift       |
    | `deleteRange`  | Delete cells with shift       |
    | `sortRange`    | Sort range data               |
    | `mergeRange`   | Merge cells                   |
    | `unmergeRange` | Unmerge cells                 |

    ### Formatting

    | Automation       | Description                |
    | ---------------- | -------------------------- |
    | `updateFormat`   | Set alignment and wrapping |
    | `updateFont`     | Set font properties        |
    | `updateFill`     | Set background color       |
    | `updateBorder`   | Set border styles          |
    | `autofitColumns` | Auto-fit column widths     |
    | `autofitRows`    | Auto-fit row heights       |

    ### Tables

    | Automation            | Description             |
    | --------------------- | ----------------------- |
    | `listTables`          | List tables in workbook |
    | `getTable`            | Get table details       |
    | `createTable`         | Create table from range |
    | `updateTable`         | Update table properties |
    | `deleteTable`         | Delete table            |
    | `addTableRow`         | Add row to table        |
    | `updateTableRow`      | Update row values       |
    | `deleteTableRow`      | Delete row              |
    | `addTableColumn`      | Add column              |
    | `deleteTableColumn`   | Delete column           |
    | `applyTableSort`      | Sort table              |
    | `applyTableFilter`    | Filter table            |
    | `clearTableFilter`    | Clear filters           |
    | `convertTableToRange` | Convert to normal range |

    ### Charts

    | Automation          | Description              |
    | ------------------- | ------------------------ |
    | `listCharts`        | List charts in worksheet |
    | `getChart`          | Get chart details        |
    | `addChart`          | Create chart             |
    | `updateChart`       | Update properties        |
    | `deleteChart`       | Delete chart             |
    | `setChartData`      | Change data source       |
    | `setChartPosition`  | Position chart           |
    | `getChartImage`     | Export as image          |
    | `updateChartTitle`  | Set title                |
    | `updateChartLegend` | Configure legend         |

    ### Named Items & Pivot Tables

    | Automation              | Description             |
    | ----------------------- | ----------------------- |
    | `listNamedItems`        | List named ranges       |
    | `getNamedItem`          | Get named item value    |
    | `addNamedItem`          | Create named range      |
    | `updateNamedItem`       | Update named item       |
    | `listPivotTables`       | List pivot tables       |
    | `getPivotTable`         | Get pivot table details |
    | `refreshPivotTable`     | Refresh pivot table     |
    | `refreshAllPivotTables` | Refresh all             |

    ### Functions

    | Automation             | Description            |
    | ---------------------- | ---------------------- |
    | `executeExcelFunction` | Execute Excel function |

    ## DSUL Examples

    ### Read a Range

    ```yaml theme={null}
    - Excel.getRange:
        itemId: "01ABCDEF..."
        worksheetId: Sheet1
        address: "A1:C10"
        output: data
    ```

    ### Write Values

    ```yaml theme={null}
    - Excel.updateRange:
        itemId: "01ABCDEF..."
        worksheetId: Sheet1
        address: "A1:C2"
        values:
          - ["Name", "Age", "City"]
          - ["John", 30, "New York"]
        output: result
    ```

    ### Create a Table

    ```yaml theme={null}
    - Excel.createTable:
        itemId: "01ABCDEF..."
        worksheetId: Sheet1
        address: "A1:C10"
        hasHeaders: true
        output: table
    ```
  </Tab>

  <Tab title="Usage as MCP">
    ## MCP Setup

    1. Open your **Knowledges project**
    2. Go to **Advanced > Tools**
    3. Click **Add** and select the **MCP** tab
    4. Enter the MCP endpoint URL
    5. In the **Headers** field, add your credentials:

    ```json theme={null}
    {
      "mcp-api-key": "your-mcp-api-key",
      "azure-client-id": "your-client-id",
      "azure-client-secret": "your-client-secret",
      "azure-tenant": "your-tenant-id",
      "azure-site-id": "your-sharepoint-site-id"
    }
    ```

    ## Authentication

    Configure workspace secrets for Azure AD Client Credentials Flow:

    | Secret              | Description                 |
    | ------------------- | --------------------------- |
    | `azureClientId`     | Azure AD client ID          |
    | `azureClientSecret` | Azure AD client secret      |
    | `azureTenant`       | Azure AD tenant ID          |
    | `azureSiteId`       | Optional SharePoint site ID |

    ## File Access

    **OneDrive files** - provide only `itemId`:

    ```json theme={null}
    { "itemId": "01ABCDEF..." }
    ```

    **SharePoint files** - provide `itemId` and `siteId`:

    ```json theme={null}
    {
      "itemId": "01ABCDEF...",
      "siteId": "contoso.sharepoint.com,abc-123,def-456"
    }
    ```

    **SharePoint with specific drive** - add `driveId`:

    ```json theme={null}
    {
      "itemId": "01ABCDEF...",
      "siteId": "contoso.sharepoint.com,abc-123,def-456",
      "driveId": "b!xyz..."
    }
    ```

    ## Available Tools

    All 50+ automations listed in the App tab are available as MCP tools with the same names and parameters.

    ### Tool Categories

    * **Workbook**: `createWorkbook`, `calculateWorkbook`
    * **Worksheets**: `listWorksheets`, `getWorksheet`, `addWorksheet`, `updateWorksheet`, `deleteWorksheet`, `getUsedRange`
    * **Ranges**: `getRange`, `updateRange`, `getCell`, `clearRange`, `insertRange`, `deleteRange`, `sortRange`, `mergeRange`, `unmergeRange`
    * **Formatting**: `updateFormat`, `updateFont`, `updateFill`, `updateBorder`, `autofitColumns`, `autofitRows`
    * **Tables**: `listTables`, `getTable`, `createTable`, `updateTable`, `deleteTable`, `addTableRow`, `updateTableRow`, `deleteTableRow`, `addTableColumn`, `deleteTableColumn`, `applyTableSort`, `applyTableFilter`, `clearTableFilter`, `convertTableToRange`
    * **Charts**: `listCharts`, `getChart`, `addChart`, `updateChart`, `deleteChart`, `setChartData`, `setChartPosition`, `getChartImage`, `updateChartTitle`, `updateChartLegend`
    * **Named Items**: `listNamedItems`, `getNamedItem`, `addNamedItem`, `updateNamedItem`
    * **Pivot Tables**: `listPivotTables`, `getPivotTable`, `refreshPivotTable`, `refreshAllPivotTables`
    * **Functions**: `executeExcelFunction`

    ## JSON-RPC Examples

    ### Read a Range

    ```json theme={null}
    {
      "name": "getRange",
      "arguments": {
        "itemId": "01ABCDEF...",
        "worksheetId": "Sheet1",
        "address": "A1:C10"
      }
    }
    ```

    ### Write Values

    ```json theme={null}
    {
      "name": "updateRange",
      "arguments": {
        "itemId": "01ABCDEF...",
        "worksheetId": "Sheet1",
        "address": "A1:C2",
        "values": [
          ["Name", "Age", "City"],
          ["John", 30, "New York"]
        ]
      }
    }
    ```

    ## Output Formats

    All tools support an `outputFormat` parameter:

    * **`verbose`** (default) - Human-readable text for LLM consumption
    * **`structured`** - Machine-readable JSON in `structuredContent`
    * **`both`** - Both text and structured content
  </Tab>
</Tabs>

***

## Error Handling

| HTTP Status | Error        | Solution                 |
| ----------- | ------------ | ------------------------ |
| 401         | Unauthorized | Reconfigure credentials  |
| 403         | Forbidden    | Check app permissions    |
| 404         | Not Found    | Verify item ID exists    |
| 423         | Locked       | Close file in Office app |
| 429         | Rate Limited | Wait and retry           |

### Common Issues

**"File is locked"** - The Excel file is open in the desktop application. Close it or wait for auto-save.

**"Invalid range address"** - Use A1 notation (e.g., "A1:C10", not row/column numbers).

**"Range too large"** - Excel API limits requests to 5 million cells. Split into smaller ranges.

**".xls not supported"** - Only .xlsx files are supported. Convert legacy files first.

## Rate Limits

| Limit                 | Value                     |
| --------------------- | ------------------------- |
| Per-app (all tenants) | 5,000 requests/10 seconds |
| Per-app per-tenant    | 1,500 requests/10 seconds |
| Max cells per request | 5,000,000                 |
| Max file size         | 25 MB                     |

When rate limited, the API returns HTTP 429 with a `Retry-After` header.

## External Resources

<CardGroup cols={2}>
  <Card title="Microsoft Graph Excel API" icon="book" href="https://learn.microsoft.com/en-us/graph/api/resources/excel">
    Official API documentation
  </Card>

  <Card title="Excel API Best Practices" icon="lightbulb" href="https://learn.microsoft.com/en-us/graph/workbook-best-practice">
    Performance optimization tips
  </Card>

  <Card title="Graph Explorer" icon="flask" href="https://developer.microsoft.com/en-us/graph/graph-explorer">
    Test API calls interactively
  </Card>

  <Card title="MCP Specification" icon="robot" href="https://modelcontextprotocol.io">
    Model Context Protocol specification
  </Card>
</CardGroup>