office-mcp

Office MCP Server > **AI-Powered Office Automation** - Intelligent Office Document Processing Service based on [ [](LICENSE) [](https://modelcontextprotocol.io/) ## 📋 Project Overview Office MCP Server is an Office document automation service based on the **Model Context Protocol (MCP)**, supporting operation of Word, Excel, and PowerPoint documents through natural language### Core Features - ✅ **Word Document Processing**: Create, edit, and format Word documents - ✅ **Excel Spreadsheet Processing**: Data manipulation, formula calculation, and chart generation - ✅ **PowerPoint Presentation**: Slide creation, content layout, and style settings - ✅ **Read/Write Support**: Support for reading and writing existing documents (Python solution advantages) - ✅ **PDF Conversion**: Native support for PDF generation and conversion - ✅ **AI Integration**: Seamless integration with Claude, Cursor, and other AI clients ### Reference Projects This project references the successful implementation of [GongRzhe/Office-Word-MCPhttps://github.com/GongRzhe/Office-MCP-Server) (960+ stars), using a FastMCP technology stack. ## ⚠️ Functional Limitations This project is implemented based on Python's Office processing libraries (`python-docx`, `openpyxl`, `python-ppt covering **85%+ of daily office automation needs**. However to technical stack limitations Microsoft Office proprietary features are. ### Excel Functional Limitations | Feature Category | Limitation Description | Technical Reason | Alternative Solution | |---------|---------|---------|--------- **🔧 VBA Macros and Automation** | Does not support VBA macro execution, recording, and editing | `openpyxl` library does not support VBA macro engine | Use Python scripts for automation logic | | **📊 Pivot Tables** | Basic functionality available, but cross-platform support is limited | `openpyxl` has limited support for pivot tables; complete functionality requires Windows + `pywin32` | Basic creation and refresh functionality implemented; suggest using Excel application for complex scenarios | | **🔍 Power Query** | Does not support data retrieval and transformation features | Power Query is an Excel proprietary feature; no open-source implementation | Use Python's `pandas` for data processing | | **📈 Power Pivot** | Does not support data modeling, DAX formulas, KPIs | Power Pivot is an Excel proprietary feature | Use Python data analysis libraries (e.g., `pandasnumpy`) | | **👥 Shared Workbooks** | Does not support multi-user collaborative editing and change history |pyxl` does not support shared workbook protocol | Use version (e.g., Git) for file version management | | **🎯 Advanced What-If Analysis** | Does data tables and scenario managers | These are Excel's interactive tools | Single-variable solving (goal search) supported; other scenarios can be implemented with Python | ### PowerPoint Functional Limitations | Feature Category | Limitation Description | Technical Reason | Alternative Solution | |---------|---------|---------|---------| | **🎬 Animations** | Animation support is very limited; only basic markers are provided | `python-pptx` has incomplete API support for animations; complete functionality requires Windows + `win32com` | Manually add complex animations in PowerPoint or use basic animation effects | 🎨 SmartArt Graphics** | Does not support Smart and editing | SmartArt is a Microsoft Office proprietary feature; `python-pptx` does not support | Use shape combinations to simulate SmartArt effects | | **🎵 Audio and Video** | Does not support audio and video file embedding | `python-pptx` library does not support multimedia embedding | Manually add audio/video in PowerPoint | | **📐 Master Editing** | Does not support complete editing of slide masters | `python-pptx` has very limited support for masters | Use preset templates or edit masters in PowerPoint | | **📋 Advanced Table Operations** | Does not support deleting rows/columns, splitting cells, adjusting row/column width | `python-pptx` table operation API is limited | Basic table creation, data filling, and cell merging are supported | ### Word Functional Limitations | Feature Limitation Description | | Alternative Solution | |---------|---------|---------|---------| | **📝 Footnotes and Endnotes** | Does not support editing of footnotes and endnotes | `python` library does not support footnote/endnote API | Use or paragraph notes as alternatives | | **🔗 Cross** | Does not support creation and updating of cross | `python-docx` has limited support for field Use hyperlinks or | | **📋 Track Changes** | Does not support complete track changes and comment functionality | `python-docx` has very limited support for track changes | Use version control systems (e.g., Git) for document version management | | **🔒 Document Protection** | Does not support document protection and permission control | `python-docx` does not support document protection API | Use or manually set protection in Word | | **📐 Field Codes Support for field codes limited; only basic date are supported | `x` field code incomplete | Basic date/time fields are supported; complex manual addition in Word | ### Features Requiring Additional System| Feature Category | Limitation Description | Technical Reason Solution | |---------|---------| | **🏢** | Does not support brand template management, generation, workflow integration | These are advanced business features requiring additional Use Python scripts processing logic | | **☁️ Online Collaboration** | Does not support OneDrive, SharePoint integration | Requires365 API integration | Use local file systems or third-party cloud storage | | **🌐 Multi-Language Support** | Does not support automatic translation and multi-language proofreading | Requires integration with translation APIs | Use translation services | | **📊 Document Analysis** not support readability analysis, keyword extraction, and other advanced analysis NLP library support | Use Python NLP libraries (e.g., spaCy, NLTK) for implementation | ### Fully Supported Core Features ✅ Despite the above limitations, this project fully implements the following features, sufficient to meet most office automation scenarios: <details> <summary><b>📝 Excel Core Features (Click to Expand)</b></summary> - ✅ **Workbook and Worksheet Management**: Create, open, save, copy, protect - ✅ **Data Operations**: Cell read/write, batch data processing, data clearing - ✅ **Formulas and Functions**: 100+ common functions (SUM, VLOOKUP, IF, etc.) - ✅ **Data Formatting**: Font, color, alignment, border, conditional formatting - ✅ **Data Sorting and Filtering**: Multi-column sorting, color sorting, auto-filtering - ✅ **Chart Creation**: Column charts, line charts, pie charts, scatter plots, combination charts, trend lines - ✅ **Row and Column Operations**: Insert, delete, hide, resize, copy, move - ✅ **Data Import/Export**: CSV, JSON, PDF, HTML format conversion - ✅ **Printing Settings**: Page setup, margins, print area, page breaks - ✅ **Data Analysis**: Descriptive statistics, regression analysis, variance analysis, t-tests, trend prediction - ✅ **Collaboration Features**: Comment addition, viewing, deletion - ✅ **Security Features**: Workbook encryption, cell locking, data masking - ✅ **Batch Processing**: Batch file processing, workbook merging, report automation </details> <details> <summary><b>📄 Word Core Features (Click to Expand)</b></summary> - ✅ **Document Basic Operations**: Create, open, save, insert text, add titles, page breaks - ✅ **Text Editing and Formatting**: Font settings, character styles, paragraph formats, list formats, regular expression find/replace (new) - ✅ **Special Characters**: Insert 40+ special characters (copyright, trademark, mathematical symbols, arrows, currency symbols, etc.) (new) - ✅ **Styles and Themes**: Apply built-in styles, create custom paragraph styles, list all styles (new) - ✅ **Table Operations**: Create tables, fill data, read data, insert/delete rows/columns, merge cells, format tables, table sorting, data import (new) - ✅ **Images and Multimedia**: Insert images from files/URLs, complete size and alignment control (new) - ✅ **Headers and Footers**: Add headers and footers, insert page numbers, different first page, odd/even page differences (new), insert date/time fields (new) - ✅ **Table of Contents and References**: Generate table of contents - ✅ **Bookmarks and Hyperlinks**: Add/delete bookmarks, add/edit/delete hyperlinks, batch update hyperlinks (new) - ✅ **Document Metadata**: Get and set document properties (author, title, subject, keywords, etc.) (new) - ✅ **Content Extraction**: Extract text, paragraphs, table data, image information, hyperlinks, document statistics - ✅ **Export Features**: Export to PDF, HTML, TXT, Markdown, RTF - ✅ **Batch Operations**: Batch replace text, batch apply styles, batch convert formats (new), batch add headers and footers (new), batch insert content (new) - ✅ **Advanced Features**: Mail merge, document merging, document splitting, multilevel lists (new) </details> <details> <summary><b>🎨 PowerPoint Core Features (Click to Expand)</b></summary> - ✅ **Presentation Management**: Create, open, save, get information -Slide Operations**: Add, delete, move, copy, layout settings - ✅ **Text Processing**: Insert text boxes, character formats, paragraph formats, bullet points - ✅ **Image Operations**: Insert images, resize, set position - ✅ **Table Features**: Create tables, fill data, merge cells, format tables - ✅ **Shape Drawing**: Rectangles, ellipses, triangles, arrows, rounded rectangles - ✅ **Chart Creation**: Column charts, line charts, pie charts, bar charts, area charts - ✅ **Style Settings**: Apply themes, set backgrounds, transition effects - ✅ **Presenter Notes**: Add, get, edit notes - ✅ **Hyperlinks**: Web links, slide links, file links, email links - ✅ **Batch Operations**: Batch set transitions, batch add footers - ✅ **Content Extraction**: Extract text, titles, notes, image information, hyperlinks (new) - ✅ **Export Features**: Export to PDF (requires PowerPoint application), HTML </details> ### 💡 Usage Suggestions Usage Suggestions 1. **Daily Office Automation**: This project fully meets requirements; no need to worry about functional limitations 2. **Data Analysis Scenarios**: Provides rich statistical analysis tools; can replace most Excel analysis functions 3. **Complex VBA Macros**: Suggest replacing with Python scripts for easier maintenance and cross-platform compatibility 4. **Enterprise-Level Data Modeling**: Recommend using professional BI tools (e.g., Power BI, Tableau) or Python data analysis stack #### PowerPoint Usage Suggestions 1. **Presentation Creation and Editing**: Core features are complete; meets daily presentation needs 2. **Complex Animation Effects**: Suggest manually adding in PowerPoint or using basic animation effects 3. **Multimedia Content**: Audio/video must be manually added in PowerPoint 4. **SmartArt Graphics**: Can use shape combinations to achieve similar effects 5. **Batch Processing**: Utilize Python scripts for batch presentation generation and processing 6. **Content Analysis**: Use the new content extraction feature to analyze presentation structure #### Word Usage Suggestions 1. **Daily Document Processing**: Core features are complete; meets most document creation and editing needs 2. **Enhanced Text Editing**: Use regular expression find/replace for complex text patterns 3. **Style Management**: Create custom styles for unified document formatting and increased efficiency 4. **Batch Processing**: Utilize batch operations to process and save time 5. **Content Extraction**: Use content extraction to analyze document structure and data 6. **Footnotes and Cross-References**: These features are limited; suggest manual addition in7. **Document Use PDF format or manually set protection in Word 8. **Complex Field Codes**: Basic date/time fields; complex fields suggest manual addition in Word ### 📊 Feature Coverage | Office Application | Feature Category | Description | |-----------|---------|-------|------| | **📊 Excel** | Core Office Features | **95%+** | Workbooks, data, formatting, formulas, charts, etc. | | **📊 Excel** | Data Analysis Features | **90%+** | Statistical analysis, predictive analysis, data visualization | | **📊 Excel** | Collaboration and Security | **70%** | Comments, encryption, permission control (excludes shared workbooks) | | **📊 Excel Advanced Proprietary Features | **20%** | VBA, Power Query, Power Pivot, etc. | | **📊 Excel** | **Overall Coverage** | **✅ 85%+** | Meets most office automation needs | | **🎨 PowerPoint** | Core Presentation Features | **90%+** | Slide management, images, tables, charts | | PowerPoint** | Styles and Design |** | Themes, backgrounds, transitions (limited animation support) | | **🎨 PowerPoint** | Content Extraction | **100%** | Text, titles, notes, image information, hyperlink extraction | | **🎨 PowerPoint** | Advanced Proprietary Features10%** | SmartArt, audio/video, enterprise features | | **🎨 PowerPoint** | **Overall Coverage**✅ 60** | Meets daily presentation creation and editing needs | | **📄 Word** | Core Document Features95%+** | Document creation, editing, tables, images (new features) | | **📄 Word** | Enhanced Text Editing | **+** | Regular expressions, special characters, (new) | 📄 Word Styles and Formatting | **75%** | styles, custom styles (partial support) | | **📄 Word** | Content Extraction | **100%** | Text, tables, images, hyperlinks, metadata extraction | 📄 Word** | Batch Operations | **85%+** | Batch conversion, batch formatting, batch insertion (new) | 📄 Word Advanced Proprietary Features | **20%** | Footnotes, cross-re track changes, VBA macros, etc. | | **📄 Word** | **Overall Coverage** | **✅ 70%+** | Meets daily document processing needs; 15+ new tools added | | **🎯 Project Overall** | **Comprehensive Coverage** | **✅ 75%+** | Covers core features of three Office applications | ## 🚀 Quick Start ### Prerequisites - **Python**: 3.10 or higher (recommended 3.11+) - **Operating System**: Windows 10/11, macOS 10.15+, or Linux AI Client**: Claude Desktop, Cursor, or other MCP-supported clients ### Installation Steps #### Method 1: Using pip (Recommended) ```bash # Clone repository git clone https://github.com/your-username/office-mcp-server.git cd office-mcp-server # Create virtual environment python -m venv venv # Activate virtual environment # Windows venv\Scripts\activate # macOS/Linux source venv/bin/activate # Install dependencies pip install -r requirements.txt # Run server python src/main.py ``` #### Method 2: Using uv (Faster) ```bash # Installpip install uv # Clone repository gitgithub.com/your-username/office-mcp-server.git cd office-mcp-server # Install dependencies using uv uv pip install -r # Run server python src/main.py ``` #### Method 3: Using uvx (No Installation) ```bash # Run directly (if published to PyPI) uvx office-mcp-server ``` ## 🛠️ Technology Stack | Component | Technology | Version | Description | |------|------|------|------| | **Runtime Environment** | Python | 3.10+ | Recommended 3.11 or 3.12 | | **MCP SDK** | FastMCP | Latest | Simplifies MCP development | | **Word** | python-docx | 1.1.0+ | ✅ Supports read/write | | **Excel** | openpyxl | 3.1.0+ | ✅ Supports read/write | | **PowerPoint** | python-pptx | 0.6.23+ | ✅/write | | **PDF** | reportlab4.0+ | PDF generation | |** | Pillow | 10.0+ | Image processing | --- ## 📦 Project Structure ``` office-mcp-server/ ├── src/ │ ├── main.py # MCP Server Main Entry │ ├── config.py # Configuration Management │ ├── handlers/ # Business Logic Layer │ │ ├── word_handler.py # Word Document Handling │ │ ├── excel_handler.py # Excel Spreadsheet Handling │ │ └── ppt_handler.py # PowerPoint Presentation Handling │ ├── tools/ # MCP Tool Definition Layer │ │ ├── word_tools.py # Word MCP Tools │ │ ├── excel_tools.py # Excel MCP Tools │ │ └── ppt_tools.py # PPT MCP Tools │ └── utils/ # Utility Function Layer │ ├── file_manager.py # File Management │ └── format_helper.py # Formatting Assistant ├── tests/ # Test Directory ├── docs/ # Documentation Directory ├── requirements.txt # Dependency List ├── pyproject.toml # Project Configuration └── README.md # Project Description ``` --- ## ⚙️ Client Configuration ### Cursor Editor 1. Open MCP Settings: `Ctrl+Shift+P` → `View: Open MCP Settings` 2. Edit configuration file (Windows: `%APPDATA%\Cursor\mcp.json`) ```json { "mcpServers": { "office-suite": { "command": "python", "args": ["C:\\path\\to\\office-mcp-server\\src\\main.py"], "env": { "PYTHONPATH": "C:\\path\\to\\office-mcp-server" } } } } ``` ### Claude Desktop Edit configuration file (Windows: `%APPDATA%\Claude\claude_desktop_config.json`) ```json { "mcpServers": { "office-suite": { "command": "python", "args": ["/path/to/office-mcp-server/src/main.py"] } } } ``` ### Using uvx (Recommended) ```json { "mcpServers": { "office-suite": { "command": "uvx", "args": ["office-mcp-server"] } } } ``` --- ## 💡 Usage Examples ### Example 1: Create Word Document **User Instruction**: ``` Please create a Word document named "Project Report.docx" with the title "2024 Annual Project Summary". ``` **AI Automatic Invocation**: ```python create_word_document( filename="Project Report.docx", title="2024 Annual Project Summary", content="This report summarizes the main project achievements in 2024." ) ``` ### Example 2: Generate Excel Report **User Instruction**: ``` Create a sales data table with product names and sales amounts, and generate a bar chart. ``` **AI Automatic Invocation**: ```python create_excel_workbook(filename="Sales Report.xlsx") write_excel_data(filename="Sales Report.xlsx", data=[...]) create_excel_chart(filename="Sales Report.xlsx", chart_type="bar", ...) ``` ### Example 3: Create PowerPoint Presentation **User Instruction**: ``` Create a PPT for product introduction with a title page and a feature list page. ``` **AI Automatic Invocation**: ```python create_presentation(filename="Product Introduction.pptx", title="New Product Launch") add_slide_with_content(filename="Product Introduction.pptx", title="Core Features", content=[...]) ``` --- ## 🧪 Testing ```bash # Run all tests pytest # Run specific test pytest tests/test_word.py # Generate coverage report pytest --cov=src --cov-report=html ``` --- ## 📚 Documentation - [Technical Design](OFFICE_MCP技术方案设计.md) - Complete technical architecture and implementation plan - [Development Plan](OFFICE_MCP开发计划.md) - Detailed development roadmap - [Service Integration Guide](OFFICE_MCP服务集成指南.md) - Client integration guide - [Word Feature Description](WORD_MCP功能说明文档.md) - Word feature detailed description - [Excel Feature Description](EXCEL_MCP功能说明文档.md) - Excel feature detailed description - [PowerPoint Feature Description](POWERPOINT_MCP功能说明文档.md) - PowerPoint feature detailed description --- ## 🤝 Contribution Welcome to contribute code, report issues, or propose suggestions! 1. Fork this repository 2. Create a feature branch (`git checkout -b feature/AmazingFeature`) 3. Commit changes (`git commit -m 'Add some AmazingFeature'`) 4. Push to the branch (`git push origin feature/AmazingFeature`) 5. Open a Pull Request --- ## 📄 License This project is licensed under the MIT License - see [LICENSE](LICENSE) file --- ## 🙏 Acknowledgements - [Anthropic](https://www.anthropic.com/) - MCP Protocol Developer - [GongRzhe/Office-Word-MCP-Server](https://github.com/GongRzhe/Office-Word-MCP-Server) - Reference implementation - [python-docx](https://python-docx.readthedocs.io/) - Word document processing library - [openpyxl](https://openpyxl.readthedocs.io/) - Excel spreadsheet processing library - [python-pptx](https://python-pptx.readthedocs.io/) - PowerPoint presentation processing library --- ## 📞 Contact - **Project Homepage**: https://github.com/your-username/office-mcp-server - **Issue Tracker**: https://github.com/your-username/office-mcp-server/issues - **Discussion Forum**: https://github.com/your-username/office-mcp-server/discussions --- **⭐ If this project helps you, please give it a Star!**