photonn/basic-excel-mcp

Basic Excel MCP Server

A Model Context Protocol (MCP) server for converting Excel files (.xlsx, .xls, .csv) to Markdown format for LLM processing. This server can run locally, in Docker, or in a Kubernetes cluster.

Features

• Convert Excel files to Markdown tables
• Support for multiple Excel formats (.xlsx, .xls, .csv)
• Specific sheet selection for Excel files
• Column metadata and statistics
• Kubernetes-ready deployment
• Base64 file input support

Installation

Local Development

1. Clone the repository:

   git clone <your-repo-url>
   cd basic-excel-mcp
   

2. Install dependencies:

   pip install -e .
   

3. Run the server:

   python server.py
   

Docker

1. Build the Docker image:

   make docker-build
   # or
   docker build -t basic-excel-mcp:latest .
   

2. Run with Docker:

   make docker-run
   # or
   docker run -p 8080:8080 basic-excel-mcp:latest
   

3. Run with Docker Compose:

   make docker-compose-up
   # or
   docker-compose up -d
   

Kubernetes

1. Deploy to Kubernetes:

   make k8s-deploy
   # or
   kubectl apply -f k8s-deployment.yaml
   

2. Check deployment status:

   make k8s-status
   # or
   kubectl get pods -l app=basic-excel-mcp
   kubectl get services basic-excel-mcp-service
   

3. View logs:

   make k8s-logs
   # or
   kubectl logs -l app=basic-excel-mcp -f
   

4. Clean up:

   make k8s-clean
   # or
   kubectl delete -f k8s-deployment.yaml
   

Usage

MCP Protocol

The server implements the Model Context Protocol and provides one main tool:

excel_to_markdown

Converts Excel files to Markdown format.

Parameters:

• file_content (string, required): Base64 encoded Excel file content
• file_name (string, required): Original filename with extension
• sheet_name (string, optional): Specific sheet name to convert
• include_index (boolean, optional): Whether to include row index (default: false)

Example Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "excel_to_markdown",
    "arguments": {
      "file_content": "TmFtZSxBZ2UsQ2l0eQpKb2huIERvZSwzMCxOZXcgWW9yaw==",
      "file_name": "sample.csv",
      "include_index": false
    }
  }
}

Example Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "# Excel File: sample.csv\n\n**Rows:** 2\n**Columns:** 3\n\n| Name     | Age | City     |\n|:---------|----:|:---------|\n| John Doe |  30 | New York |\n| Jane Smith |  25 | Los Angeles |\n\n## Column Information\n\n- **Name**: object (2 non-null values)\n- **Age**: int64 (2 non-null values)\n- **City**: object (2 non-null values)\n"
      }
    ]
  }
}

Testing

Run the test client to verify the server is working:

make test
# or
python test_client.py

Development

Available Make Commands

• make install - Install the package locally
• make run - Run the server locally
• make test - Run the test client
• make docker-build - Build Docker image
• make docker-run - Run Docker container
• make k8s-deploy - Deploy to Kubernetes
• make k8s-clean - Remove from Kubernetes
• make k8s-logs - View Kubernetes logs
• make k8s-status - Check Kubernetes status

Project Structure

basic-excel-mcp/
├── server.py              # Main MCP server implementation
├── test_client.py         # Test client for development
├── pyproject.toml         # Python package configuration
├── Dockerfile            # Docker container configuration
├── docker-compose.yml    # Docker Compose configuration
├── k8s-deployment.yaml   # Kubernetes deployment manifest
├── Makefile             # Development commands
├── README.md            # This file
└── .gitignore          # Git ignore rules

Kubernetes Configuration

The Kubernetes deployment includes:

• Deployment: 3 replicas with resource limits
• Service: ClusterIP service exposing port 80
• Health checks: Liveness and readiness probes
• Resource limits: 512Mi memory, 500m CPU

Scaling

To scale the deployment:

kubectl scale deployment basic-excel-mcp --replicas=5

Monitoring

Check pod status and logs:

# Get pod status
kubectl get pods -l app=basic-excel-mcp

# View logs
kubectl logs -l app=basic-excel-mcp -f

# Describe deployment
kubectl describe deployment basic-excel-mcp

Configuration

Environment Variables

• PYTHONUNBUFFERED=1 - Ensures Python output is not buffered

Resource Requirements

• Memory: 256Mi request, 512Mi limit
• CPU: 250m request, 500m limit

Troubleshooting

Common Issues

1. Server not responding: Check if the process is running and listening on the correct port
2. Memory issues: Increase resource limits in k8s-deployment.yaml
3. File encoding errors: Ensure files are properly base64 encoded

Debug Commands

# Check server logs in Kubernetes
kubectl logs -l app=basic-excel-mcp

# Check service endpoints
kubectl get endpoints basic-excel-mcp-service

# Debug pod issues
kubectl describe pod <pod-name>

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes and test locally
4. Submit a pull request

License

MIT License - see LICENSE file for details.