Excel Online

An MCP (Model Context Protocol) server that integrates with your OneDrive and Excel Workbooks, to enable creating and modifying work sheets using the Microsoft Graph API.

---

🚀 Quick Start (Using uvx)

Essentially the server runs in one line: uvx mcp-excel-online@latest.

This command will automatically download the latest code and run it. It is recommended to always use @latest to ensure you have the newest version with the latest features and bug fixes.

1. ☁️ Prerequisite: Azure App Registration

   • You must configure an Azure Entra ID (Azure AD) app registration and grant the necessary Microsoft Graph API permissions first.
   • ➡️ Jump to the Azure App Registration guide below.

2. Install uv

   • Installation guide

3. 🔑 Set Essential Environment Variables

   • You need to tell the server how to authenticate. Set these variables in your terminal:

   • (Linux/macOS)

     export APP_CLIENT_ID="your-client-id"
     export APP_TENANT_ID="your-tenant-id"       # required for application permissions
     export APP_CLIENT_SECRET="your-client-secret" # required for application permissions
     export DRIVE_ID="your-drive-id"
     

   • (Windows CMD)

     set APP_CLIENT_ID="your-client-id"
     set APP_TENANT_ID="your-tenant-id"
     set APP_CLIENT_SECRET="your-client-secret"
     set DRIVE_ID="your-drive-id"
     

   • (Windows PowerShell)

     $env:APP_CLIENT_ID = "your-client-id"
     $env:APP_TENANT_ID = "your-tenant-id"
     $env:APP_CLIENT_SECRET = "your-client-secret"
     $env:DRIVE_ID = "your-drive-id"
     

   • ➡️ See Environment Variables for the full list of options.

4. 🏃 Run the Server!

   • uvx will automatically download and run the latest version of mcp-excel-online:

     uvx mcp-excel-online@latest
     

   • The server will start and print logs indicating it's ready.

   💡 Pro Tip: Always use @latest to ensure you get the newest version with bug fixes and features. Without @latest, uvx may use a cached older version.

5. 🔌 Connect your MCP Client

   • Configure your client (e.g., Claude Desktop) to connect to the running server.
   • Depending on the client you use, you might not need step 4 because the client can launch the server for you. But it's a good practice to test run step 4 anyway to make sure things are set up properly.

6. ⚡ Optional: Enable Tool Filtering (Reduce Context Usage)

   • By default, all tools are enabled. To reduce context usage, enable only the tools you need.
   • ➡️ See Available tool names for `--include-tools` for details.

Set up is complete, you can now start issuing commands via your MCP client.

---

📖 Table of Contents

• MCP Excel Online
  • 🚀 Quick Start (Using uvx)
  • 📖 Table of Contents
  • Features
    • Resources
    • Tools
  • Prerequisites
  • Azure App Registration
    • Permission Types
  • Environment Variables
  • Arguments
    • Available tool names for --include-tools
    • Running Locally with uv
      • 1. Clone the repository
      • 2. Create your .env file with the required environment variables (see above)
      • 3. Start the server
    • Running with Docker
      • 1. Building the image locally
      • OR Pulling the image from Docker Hub
      • 2. Run the container

---

Features

Resources

Resource	Description
drive://root/children	List all items at the root of the configured OneDrive
drive://drives/{drive_id}/root/{relative_path}/children	List items in a folder by path

Tools

Tool	Description
List Sheets	List all worksheets in a workbook
Create Worksheet	Add a new worksheet to a workbook
Rename Worksheet	Rename an existing worksheet
Delete Worksheet	Delete a worksheet from a workbook
Copy Worksheet	Copy a worksheet from one workbook to another
Get Worksheet Data	Read cell values from a worksheet (full sheet or a range)
Get Worksheet Formulas	Read formulas from a worksheet (full sheet or a range)
Update Worksheet Data	Write values to a cell range in a worksheet

---

Prerequisites

• Python 3.13+
• uv (for local development)
• Docker (for containerised deployment)
• A Microsoft Azure account with an Entra ID (Azure AD) app registration

---

Azure App Registration

Register your application by following the steps at Register your app with the Microsoft Identity Platform.

Permission Types

Application permissions are used when you don't need a user to log in to your app. The app performs tasks on its own and runs in the background using a client secret (service principal flow). Required: APP_CLIENT_ID, APP_TENANT_ID, APP_CLIENT_SECRET

Delegated permissions (scopes) are used when your app requires a user to log in and interact with data related to that user in a session. Authentication is performed via the device code flow — the server will print a URL and a code to the console. Required: APP_CLIENT_ID only

---

Environment Variables

Variable	Required	Description
APP_CLIENT_ID	Always	The Application (client) ID of your Azure app registration
APP_TENANT_ID	Application permissions only	The Directory (tenant) ID of your Azure tenant
APP_CLIENT_SECRET	Application permissions only	A client secret generated for your app registration
DRIVE_ID	Required	OneDrive Drive ID to use as the default drive
HOST	Optional	Host address the server binds to (default: 0.0.0.0)
PORT	Optional	Port the server listens on (default: 8000)

Create a .env file in the project root for local development:

APP_CLIENT_ID=your-client-id
APP_TENANT_ID=your-tenant-id        # required for application permissions
APP_CLIENT_SECRET=your-client-secret # required for application permissions
DRIVE_ID=your-drive-id

---

Arguments

Argument	Options	Default	Description
--transport	stdio, sse, streamable-http	sse	MCP transport protocol to use
--graph-permission	delegated, application	delegated	Microsoft Graph permission type (see above)
--include-tools	Comma-separated tool names	(all)	Only register the specified tools. If omitted, all tools are enabled (see below)

Available tool names for --include-tools

Tool name	Description
list_sheets	List all worksheets in a workbook
create_sheet	Add a new worksheet to a workbook
rename_sheet	Rename an existing worksheet
delete_sheet	Delete a worksheet from a workbook
copy_sheet	Copy a worksheet from one workbook to another
get_worksheet_data	Read cell values from a worksheet (full sheet or a range)
get_worksheet_formulas	Read formulas from a worksheet (full sheet or a range)
update_worksheet_data	Write values to a cell range in a worksheet

Example — expose only read-only tools:

uv run mcp-excel-online --include-tools list_sheets,get_worksheet_data,get_worksheet_formulas

---

Running Locally with uv

1. Clone the repository

git clone https://github.com/GokulSudheesh/mcp-excel-online.git
cd mcp-excel-online

2. Create your .env file with the required environment variables (see above)

3. Start the server

# SSE transport with delegated permissions (device code login)
uv run mcp-excel-online --transport sse --graph-permission delegated

# stdio transport with application permissions (service principal)
uv run mcp-excel-online --transport stdio --graph-permission application

# streamable-http transport
uv run mcp-excel-online --transport streamable-http

# Only enable specific tools
uv run mcp-excel-online --include-tools list_sheets,get_worksheet_data,get_worksheet_formulas

---

Running with Docker

1. Building the image locally

docker build -t mcp-excel-online .

OR Pulling the image from Docker Hub

docker pull batmansroomie/mcp-excel-online:main

2. Run the container

docker run --rm -p 8000:8000 \
  -e APP_CLIENT_ID=your-client-id \
  -e DRIVE_ID=your-drive-id \
  mcp-excel-online

You can also pass a .env file:

docker run --rm -p 8000:8000 --env-file .env mcp-excel-online

The server is accessible at http://localhost:8000/sse (SSE transport).

---