Excel MCP Server

Contributing to ExcelMcp

Thank you for your interest in contributing to Sbroenne.ExcelMcp! This project is designed to be extended by the community, especially to support coding agents like GitHub Copilot.

🎯 Project Vision

ExcelMcp aims to be the go-to command-line tool for coding agents to interact with Microsoft Excel files. We prioritize:

🚀 Getting Started

Development Environment

  1. Prerequisites:
    • Windows OS (required for Excel COM)
    • Visual Studio 2022 or VS Code
    • .NET 8 SDK
    • Microsoft Excel installed
  2. Setup: 
    git clone https://github.com/sbroenne/mcp-server-excel.git
cd ExcelMcp
dotnet restore
dotnet build

🚨 CRITICAL: Pull Request Workflow Required

All changes must be made through Pull Requests (PRs). Direct commits to main are prohibited.

Quick PR Process

  1. Create feature branch: git checkout -b feature/your-feature
  2. Make changes: Code, tests, documentation
  3. Push branch: git push origin feature/your-feature
  4. Create PR: Use GitHub’s PR template
  5. Address review: Make requested changes
  6. Merge: After approval and CI checks pass

📋 Detailed workflow: See DEVELOPMENT.md for complete instructions.

  1. Test Your Setup: 
    dotnet run -- pq-list "path/to/test.xlsx"

📋 Development Guidelines

Code Style

Architecture Patterns

Command Pattern

All commands follow this structure:

// Interface
public interface IMyCommands
{
    int MyOperation(string[] args);
}

// Implementation  
public class MyCommands : IMyCommands
{
    public int MyOperation(string[] args)
    {
        // Validation
        if (!ValidateArgs(args, expectedCount, "usage string"))
            return 1;
            
        // Excel automation using batch API
        var task = Task.Run(async () =>
        {
            await using var batch = await ExcelSession.BeginBatchAsync(filePath);
            return batch.Execute((ctx, ct) =>
            {
                // Use ctx.Book for workbook access
                // Your implementation
                return 0; // Success
            });
        });
        return task.GetAwaiter().GetResult();
    }
}

Critical Rules

  1. Always use batch API - Never manage Excel lifecycle manually
  2. Excel uses 1-based indexing - collection.Item(1) is the first element
  3. Use QueryTables.Add() not ListObjects.Add() - For loading Power Query data
  4. Escape user input - Always use .EscapeMarkup() with Spectre.Console
  5. Return 0 for success, 1+ for errors - Consistent exit codes

Excel COM Best Practices

Testing

Before submitting:

  1. Manual testing with various Excel files
  2. Verify Excel process cleanup - No excel.exe should remain after 5 seconds
  3. Test error conditions - Missing files, invalid arguments, etc.
  4. VBA script testing - For script-related commands, test with real VBA macros
  5. Cross-version compatibility - Test with different Excel versions if possible

🔧 Adding New Commands

1. Create Interface

// Commands/INewCommands.cs
namespace ExcelMcp.Commands;

public interface INewCommands
{
    int NewOperation(string[] args);
}

2. Implement Command Class

// Commands/NewCommands.cs
using Spectre.Console;

namespace ExcelMcp.Commands;

public class NewCommands : INewCommands
{
    public int NewOperation(string[] args)
    {
        // Implementation following established patterns
    }
}

3. Register in Program.cs

Add to the switch expression in Main():

return args[0] switch
{
    "new-operation" => newCommands.NewOperation(args),
    // ... existing commands
    _ => ShowHelp()
};

4. Update Help Text

Add your command to the help output in ShowHelp().

📝 Pull Request Process

Before Submitting

PR Description Template

## Summary
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Tested manually with Excel files
- [ ] Verified Excel process cleanup
- [ ] Tested error conditions
- [ ] VBA script execution tested (if applicable)
- [ ] No build warnings

## Checklist
- [ ] Code follows project conventions
- [ ] Self-review completed
- [ ] Updated documentation as needed

🎨 UI Guidelines

Spectre.Console Usage

// Success (green checkmark)
AnsiConsole.MarkupLine($"[green]✓[/] Operation succeeded");

// Error (red)  
AnsiConsole.MarkupLine($"[red]Error:[/] {message.EscapeMarkup()}");

// Warning (yellow)
AnsiConsole.MarkupLine($"[yellow]Note:[/] {message}");

// Info/debug (dim)
AnsiConsole.MarkupLine($"[dim]{message}[/]");

// Headers (cyan)
AnsiConsole.MarkupLine($"[cyan]{title}[/]");

Output Consistency

🐛 Bug Reports

When reporting bugs, please include:

💡 Feature Requests

Great feature requests include:

📚 Learning Resources

📦 For Maintainers

🏷️ Issue Labels

Thank you for contributing to Sbroenne.ExcelMcp! Together we’re making Excel automation more accessible to coding agents and developers worldwide. 🚀

This site is open source. Improve this page.