🟡 Intermediate ⚙️ Type: Excel AI Agent / MCP Server 💸 Free & Open Source (MIT) ⭐ 217 GitHub Stars
What is sv-excel-agent?
sv-excel-agent is an open-source tool that allows Large Language Models (LLMs) to natively read, edit, and automate Microsoft Excel spreadsheets using simple English commands.
Instead of manually writing messy formulas or Python scripts to handle massive spreadsheets, this tool acts as an autonomous AI agent for your data. It is built entirely on the Model Context Protocol (MCP)—the modern open standard that lets AI models connect directly to local tools and data sources.
The repository consists of two core parts: an Excel MCP server (excel_mcp) that hands the AI a kit of about 30 structural tools, and an Excel AI Agent Runner (excel_agent) that manages the decision-making loop as the AI modifies, formats, and updates your sheet cells.
Who is it for?
- Data analysts and accountants who want to automate repetitive cleaning, cell formatting, and reporting tasks using chat instead of complex macros.
- Developers looking to integrate native Excel file generation and editing capabilities into their custom AI bots or local scripting setups.
- Power users of AI editors (like Cursor or Claude Desktop) who want a native MCP server connection to programmatically read and modify local
.xlsxsheets on the fly. - Open-source automation teams who need an internal tool to handle complex data workbooks without passing sensitive operational files to premium, closed-source SaaS platforms.
What makes it special?
- True Native Excel Operations — It doesn’t just output flat text data or standard CSV files; the agent interacts directly with cell grids, colors, styles, borders, and advanced formatting structures.
- Model Context Protocol (MCP) Power — Built explicitly on the open protocol framework, meaning it seamlessly registers as a toolset with any MCP-compliant application.
- ~30 Specialized Spreadsheet Tools — Grants AI agents direct access to atomic functions like inserting formulas, organizing sheet layouts, applying filters, and reading precise cell coordinates.
- Proven Benchmark Accuracy — Extensively tested and evaluated using a subset of examples from SpreadsheetBench to guarantee dependable, highly accurate output results.
- Completely Free & MIT Licensed — Fully open-source with no user-seat subscriptions, data limitations, or premium features locked behind paywalls.
Requirements before you start
Ensure your system has these core requirements configured before starting the installation:
- Python 3.10 or higher — A modern, stable Python development environment is required to drive the agent packages.
- Microsoft Excel (Windows/macOS) — Highly recommended for the full setup. The execution environment relies on Excel to properly evaluate formulas and process complex layout comparisons.
- LibreOffice (Linux Fallback) — If you are building on a headless Linux server, LibreOffice can act as an alternative engine for sheet conversion, though formula matching may be slightly less accurate.
- An LLM API Provider Key — OpenRouter, OpenAI, or Anthropic keys to run the core agent thinking loop.
- Git — Required to safely clone the project repository code onto your local machine.
💡 Tip: Not sure if your environment is ready? Launch your terminal or Command Prompt and run
python --versionorpython3 --versionto verify that your version matches the requirements.
Step-by-step installation
Step 1 — Clone the repository
Open your command line window and fetch the repository code from GitHub:
git clone https://github.com/SylvianAI/sv-excel-agent.git
cd sv-excel-agentStep 2 — Create a virtual environment
Isolate your project dependencies by spinning up a clean Python virtual sandbox:
python -m venv venvActivate the sandbox environment:
- Windows:
venv\Scripts\activate - Mac/Linux:
source venv/bin/activate
Step 3 — Install the project packages
Install the server and agent runner modules in editable mode directly inside your active environment:
pip install -e .Step 4 — Configure your environment variables
Add your preferred AI orchestration API tokens so the agent runner can communicate with its brain model. For example, if using OpenRouter:
export OPENROUTER_API_KEY="your-api-key-here"(Windows Command Prompt users should use set OPENROUTER_API_KEY="your-api-key-here" instead.)
Step 5 — Run an automation script
You can call the agent runner using python script architecture to modify your local workbooks automatically. Here is how you initialize the agent runner to process a file task:
from excel_agent.agent_runner import ExcelAgentRunner, TaskInput
from excel_agent.config import ExperimentConfig
# Initialize runner with your target model configuration
runner = ExcelAgentRunner(
config=ExperimentConfig(model='openrouter:openai/gpt-5.1'),
mcp_server_url="http://127.0.0.1:8765/sse",
)
# Define your instructions and spreadsheet files
task_input = TaskInput(
instruction="Add a summary calculation row at the bottom and color highlight the final cell green.",
input_file="quarterly_data.xlsx",
output_file="final_summary_report.xlsx",
)
# Execute the asynchronous agent loop
agent_response = await runner.run_excel_agent(task_input)Common errors and fixes
| Error | What it means | How to fix it |
|---|---|---|
ModuleNotFoundError: No module named 'excel_mcp' | The core modules aren’t registered inside your active workspace profile. | Double check that your environment is activated and rerun pip install -e . explicitly in the root directory. |
Formula or design evaluation discrepancies | Running on a headless Linux system using LibreOffice to convert sheets. | For pristine formula translations and conditional style calculations, deploy your agent script files on a Windows or macOS box containing native Excel. |
Authentication / Client Request Failures | Your API configuration strings are missing or formatted incorrectly. | Verify your terminal environment pathways or check your local .env entries to ensure your model key matches the target ExperimentConfig parameter. |
Free vs Paid comparison
| Feature | sv-excel-agent (Free Open Source) | Premium Enterprise AI Add-ins |
|---|---|---|
| Base Licensing Price | $0 (Free under MIT license) | $10 to $40+ per user every month |
| Data Ownership & Privacy | ✅ High — executes updates directly inside your local computer workspace | ❌ Low — files must frequently clear external proprietary clouds |
| Extensibility & Connections | ✅ Complete — built using MCP standards to easily link with any script or IDE | ❌ Closed — restricted inside their vendor interfaces or web portals |
| Technical Setup Entry Barrier | ⚠️ Moderate — demands terminal commands, python scripts, and custom API paths | 🟢 Low — single click point-and-verify app-store installation wizards |
Bottom line: If you are comfortable working in a command line or code editor and need an extensible, zero-cost architecture that leaves you with full ownership of your data, setting up sv-excel-agent is an exceptional choice. If you want a zero-configuration point-and-click interface, commercial cloud solutions are better suited.
Alternatives — 3 similar tools
1. Microsoft Copilot in Excel
The native cloud-backed helper toolset directly integrated inside Microsoft 365. It allows users to query, highlight, and filter sheet insights via interactive side panels, but it requires an active commercial premium subscription license tier and routes your business data through Microsoft cloud pipelines.
🔗 www.microsoft.com/en-us/microsoft-365/copilot
2. OpenPyXL
The classical open-source Python library used specifically for reading and writing Excel spreadsheets (xlsx/xlsm/xltx) without an automated AI brain. You have to write out every line of cell logic and data loop manually, but it acts as the stable engine beneath almost all modern Python spreadsheet scripts.
3. Julius AI
An advanced AI data platform built for analytics and research. Users simply upload data workbooks or standard CSV files directly to their web browser workspace, allowing them to ask questions, create charts, and run math cleaning using conversation boxes.
🚀 Want more free AI tools like this?
We find, test, and write setup guides for the best free and open-source AI tools — so you don’t have to dig through GitHub yourself.Browse Free AI Tools at globalaiforce.com/shop →
📸 Follow us for daily AI tool tips and tutorials: instagram.com/globalaiforce