mcp-excel-online 0.1.3

Add your description here

MCP 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).

---