# Excel MCP Agent

An AI-powered Excel automation project built using **FastAPI**, **Model Context Protocol (MCP)**, **Groq LLM**, **HTTPX**, **JWT Authentication**, and **OpenPyXL**.

The project enables users to manipulate Excel spreadsheets through natural language by combining an AI agent, an MCP server, and a secure REST API.

---

## Architecture

```
                  Natural Language Request
                           │
                           ▼
                    Groq LLM Agent
                           │
                           ▼
                     MCP Client
                           │
                           ▼
                     MCP Server
                           │
                           ▼
                HTTPX API Client (JWT)
                           │
                           ▼
                 FastAPI REST API
                           │
                           ▼
                   Excel Workbook
```

---

## Features

- Secure REST API using JWT Authentication
- AI-powered Excel automation
- MCP Server exposing Excel tools
- Natural language interaction through Groq LLM
- CRUD operations on Excel spreadsheets
- Swagger UI documentation
- Modular project structure
- Automatic JWT handling inside the MCP server

---

## Project Structure

```
excel_project/
│
├── excel_api/
│   ├── auth.py
│   ├── main.py
│   ├── models.py
│   ├── services.py
│   └── files/
│       └── data.xlsx
│
├── excel_mcp_server/
│   ├── api_client.py
│   ├── config.py
│   └── mcp_server.py
│
├── excel_mcp_client/
│   ├── agent.py
│   ├── client.py
│   ├── llm_config.py
│   ├── main.py
│   └── prompts.py
│
├── requirements.txt
└── README.md
```

---

## Technologies Used

- Python 3
- FastAPI
- MCP (Model Context Protocol)
- Groq API
- HTTPX
- OpenPyXL
- PyJWT
- Pydantic
- Uvicorn

---

## Excel API Endpoints

### Authentication

| Method | Endpoint | Description |
|---------|----------|-------------|
| POST | `/auth/login` | Authenticate user and obtain JWT token |
| GET | `/auth/me` | Retrieve current authenticated user |

### Excel Operations

| Method | Endpoint | Description |
|---------|----------|-------------|
| POST | `/addData` | Insert data into a single Excel cell |
| POST | `/addDataRange` | Insert data into multiple Excel cells |
| DELETE | `/deleteCellData` | Clear data from a single cell |
| DELETE | `/deleteCellRange` | Clear data from a range of cells |

---

## MCP Tools

The MCP server exposes the following tools:

- add_data
- add_data_range
- delete_cell_data
- delete_cell_range

These tools internally communicate with the secured FastAPI application.

---

## Authentication Flow

```
Client
   │
   ▼
POST /auth/login
   │
   ▼
JWT Access Token
   │
   ▼
Authorization: Bearer <token>
   │
   ▼
Protected Excel APIs
```

The MCP server automatically:

- logs in to the FastAPI application
- retrieves a JWT token
- stores the token
- includes the Authorization header in every API request
- re-authenticates if required

---

## Installation

Clone the repository.

```bash
git clone https://github.com/<your-username>/excel-mcp-agent.git
```

Navigate to the project.

```bash
cd excel-mcp-agent
```

Create a virtual environment.

```bash
python -m venv .venv
```

Activate the virtual environment.

### Windows

```bash
.venv\Scripts\activate
```

### Linux/macOS

```bash
source .venv/bin/activate
```

Install dependencies.

```bash
pip install -r requirements.txt
```

---

## Environment Variables

Create a `.env` file in the project root.

```env
GROQ_API_KEY=your_groq_api_key

JWT_SECRET_KEY=your_secret_key
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30

API_BASE_URL=http://127.0.0.1:8000
API_USERNAME=admin
API_PASSWORD=admin123
```

---

## Running the FastAPI Server

```bash
uvicorn excel_api.main:app --reload
```

Swagger UI

```
http://127.0.0.1:8000/docs
```

---

## Running the MCP Server

```bash
python -m excel_mcp_server.mcp_server
```

or

```bash
mcp dev excel_mcp_server/mcp_server.py:mcp
```

---

## Running the AI Agent

```bash
python -m excel_mcp_client.main
```

Example prompts:

```
Add "John" to row 3 column 2

Insert "Apple", "Banana", "Orange" into A1:A3

Delete data from C5

Clear the range B2:D5
```

---

## Example Workflow

```
User
   │
   ▼
Natural Language Prompt
   │
   ▼
Groq LLM
   │
   ▼
MCP Client
   │
   ▼
MCP Server
   │
   ▼
FastAPI API
   │
   ▼
Excel Workbook Updated
```

---

## Future Improvements

- Multiple worksheets support
- Read/search Excel data
- Update existing cell values
- File upload support
- User management with database
- Refresh token implementation
- Role-based authorization
- Docker support

---

## License

This project is intended for learning purposes.

---