https://github.com/adrianh-za/py-mcp-excel
A Python project that exposes Excel file information via the Model Context Protocol (MCP) and a FastAPI REST API. It allows reading Excel spreadsheets to extract sheet names, sheet counts, and column information with data types.
https://github.com/adrianh-za/py-mcp-excel
fastapi fastmcp mcp python
Last synced: about 14 hours ago
JSON representation
A Python project that exposes Excel file information via the Model Context Protocol (MCP) and a FastAPI REST API. It allows reading Excel spreadsheets to extract sheet names, sheet counts, and column information with data types.
- Host: GitHub
- URL: https://github.com/adrianh-za/py-mcp-excel
- Owner: adrianh-za
- Created: 2026-06-04T20:27:46.000Z (27 days ago)
- Default Branch: main
- Last Pushed: 2026-06-04T20:31:02.000Z (27 days ago)
- Last Synced: 2026-06-04T22:12:36.777Z (26 days ago)
- Topics: fastapi, fastmcp, mcp, python
- Language: Python
- Homepage:
- Size: 36.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Excel MCP and FastAPI Server
A Python project that exposes Excel file information via the Model Context Protocol (MCP) and a FastAPI REST API. It allows reading Excel spreadsheets to extract sheet names, sheet counts, column information with data types, and sheet row data.
The point of the API is for easier testing, while the MCP server is the main focus for integration with MCP-compatible tools and agents.
## Features
- **MCP Server**: Model Context Protocol server with tools for Excel file inspection
- **REST API**: FastAPI-based HTTP endpoints for programmatic access
- **Excel Reader Library**: Core functionality for reading Excel files using pandas and openpyxl
### Available Tools & Endpoints
| Function | MCP Tool | API Endpoint | Description |
|----------|----------|---------------|-------------|
| Get sheet names | `read_sheet_names(path)` | `GET /api/excel/sheet-names?path={path}` | Returns list of sheet names in an Excel file |
| Get sheet count | `read_sheet_count(path)` | `GET /api/excel/sheet-count?path={path}` | Returns the number of sheets in an Excel file |
| Get columns with types | `read_columns(path, sheet, header_row=0)` | `GET /api/excel/columns?path={path}&sheet={sheet}&header_row={header_row}` | Returns column names and their data types from a specific sheet |
| Read sheet rows | `read_sheet_data(path, sheet, rows_to_read=10, header_row=0)` | `GET /api/excel/sheet-data?path={path}&sheet={sheet}&rows_to_read={rows_to_read}&header_row={header_row}` | Returns row data from a specific sheet as a list of value arrays |
## Prerequisites
- Python 3.14+
- pip or uv for package management
## Installation
### From Source
```bash
# Clone the repository
git clone https://github.com/adrianh-za/py-mcp-excel.git
cd py-mcp-excel
# Install dependencies using pip
pip install -e .
# Or using uv
uv pip install -e .
```
### Dependencies
- `fastapi` - Web framework for the REST API
- `mcp` - Model Context Protocol Python SDK
- `openpyxl` - Excel file reading
- `pandas` - Data manipulation and Excel parsing
- `uvicorn` - ASGI server for FastAPI
## Running the Project
### REST API Server
Start the FastAPI server:
```bash
PYTHONPATH=src uvicorn api_server.endpoints:app --host 127.0.0.1 --port 5251 --reload
```
```powershell
$env:PYTHONPATH='src'; .\.venv\Scripts\python.exe -m uvicorn api_server.endpoints:app --host 127.0.0.1 --port 5251 --reload
```
The API will be available at:
- **Swagger UI**: `http://localhost:5251/api/excel/swagger`
- **OpenAPI JSON**: `http://localhost:5251/api/excel/openapi.json`
- **ReDoc**: `http://localhost:5251/api/excel/openapi`
### MCP Server
Start the MCP server with your preferred transport:
```bash
PYTHONPATH=src python -m mcp_server.tools
```
**Optional Arguments:**
- `--transport`: `stdio` (default) | `sse` | `streamable-http`
- `--port`: `5250` (default)
Examples:
```bash
# STDIO transport (default)
PYTHONPATH=src npx @modelcontextprotocol/inspector python -m mcp_server.tools
# Streamable HTTP transport
PYTHONPATH=src python -m mcp_server.tools --transport streamable-http --port 5250
# Server-Sent Events transport
PYTHONPATH=src python -m mcp_server.tools --transport sse --port 5250
```
## MCP Inspector Configuration
Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to test and interact with the MCP server.
### Install and Run Inspector
```bash
npx @modelcontextprotocol/inspector
```
### Configuration for Streamable HTTP
- **Transport Type**: `Streamable HTTP`
- **URL**: `http://localhost:5250/mcp`
- **Connection Type**: `Via Proxy`
- **Authentication**: No custom headers or tokens required
### Configuration for STDIO
- **Transport Type**: `STDIO`
- **Command**: `python`
- **Arguments**: `-m mcp_server.tools` (with `PYTHONPATH=src` set in environment)
- **Authentication**: No custom headers or tokens required
### Configuration for SSE
- **Transport Type**: `Server-Sent Events`
- **URL**: `http://localhost:5250/sse`
- **Authentication**: No custom headers or tokens required
## API Usage Examples
### cURL Examples
```bash
# Get sheet names from an Excel file
curl "http://localhost:8000/api/excel/sheet-names?path=/path/to/file.xlsx"
# Get sheet count
curl "http://localhost:8000/api/excel/sheet-count?path=/path/to/file.xlsx"
# Get columns with types from a specific sheet
curl "http://localhost:8000/api/excel/columns?path=/path/to/file.xlsx&sheet=Sheet1"
# Get columns with custom header row
curl "http://localhost:8000/api/excel/columns?path=/path/to/file.xlsx&sheet=Sheet1&header_row=2"
# Read rows from a specific sheet
curl "http://localhost:8000/api/excel/sheet-data?path=/path/to/file.xlsx&sheet=Sheet1&rows_to_read=10&header_row=0"
```