Content
# Tool List
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io/)
[](https://fastapi.tiangolo.com/)
**SmartOffice-MCP** is a powerful, locally-prioritized **Model Context Protocol (MCP)** server and visual intelligent client, designed to enable AI Agents to directly operate, analyze, typeset, and generate Microsoft Office documents (Excel, Word, PPT, PDF).
## Pain Points & Core Value
In daily office work, do you often encounter the following problems?
- **High Office tool threshold**: Want to create professional data pivot tables, advanced formulas, and high-quality theme layouts, but can't remember Excel's cumbersome menu steps and complex Python scripts.
- **Many online template routines**: Online templates or report templates often require paid downloads or even forced membership recharge.
- **Low efficiency and repetitive labor**: Receive competitor analysis, weekly summary, sales analysis tasks, manually copy and paste, adjust alignment and color, and spend half an hour or even several hours of precious time.
**With AutoOffice-MCP, all this is solved:**
- **Natural language direct operation**: You don't need to be an Office expert, directly use **natural language** to ask (e.g., "Help me generate a sales weekly report with sum calculation and advanced blue tone layout"), AI automatically writes data and beautifies the format!
- **Screenshot one-key replication**: See others' exquisite table designs? Directly take a screenshot and send it to AI, the system can **intelligently replicate** 1:1 format alignment, exquisite color matching, and self-contained formula native Excel templates, saving exploration time and template fees.
- **Efficiency index-level increase**: Shorten the original half-hour or even several hours of cumbersome layout and data sorting work to **a few minutes** of full automatic completion!
## Recommended Models
To obtain the best automated tool calling accuracy and layout stability, this project strongly recommends using the following two models:
- **Google Gemini 3.5 Flash** (officially recommended, extreme speed, supports complex multi-step tool calls)
- **OpenAI GPT-4o** (extremely logical, layout and script writing stability is extremely high)
> ⚠️ *Note: Other lightweight or early version models (such as some Flash-Lite, Mini, etc.) may have function call parameter loss or format incompatibility under complex Office automation instructions, and are not recommended for production environments.*
## Key Features
- **Excel intelligent processing and data visualization**:
- Automatically insert SUM/AVERAGE formulas, grid border alignment, and professional color themes.
- Data pivot table construction, chart generation, and Pandas in-depth data analysis.
- Supports direct running of advanced Python layout and calculation scripts.
- **Word and PDF template processing**:
- Dynamic filling and batch generation of Word templates based on Jinja2 syntax.
- PDF form domain analysis, automatic filling, and text coordinate layout detection.
- **Asynchronous multi-threaded engine (Async & Multi-threaded)**:
- Adopt FastAPI and Starlette background thread pool (`run_in_threadpool`), tool execution is completely non-blocking, supports multi-page concurrent requests.
- **Modern visual intelligent client (Web Client)**:
- Provides a beautiful conversation timeline, 0ms instant connection feedback, eliminating waiting and blanking.
- SSE real-time streaming response, built-in automated tool calling status display and collapsible detailed debugging parameters (JSON Inspector).
- **Security sandbox protection**:
- Strict working directory isolation and path verification, thoroughly eliminating directory traversal vulnerabilities.
## Showcase
SmartOffice-MCP has extremely high table understanding and style reconstruction capabilities. The following are actual rendering effects of AI Agent automatically generating and replicating Excel tables:
### Table Replication
| Original Sample | AI Replicated Result |
| :---: | :---: |
|  |  |
### Auto-Generated Tables
| Business Layout Style 1 | Business Layout Style 2 |
| :---: | :---: |
|  |  |
## Quick Start
### 1. Environment Installation
Ensure you have installed Python 3.10 or higher. Run in the project root directory:
```bash
# Create a virtual environment (optional but recommended)
python -m venv .venv
# Windows activate environment
.\.venv\Scripts\activate
# Mac/Linux activate environment
source .venv/bin/activate
# Install project and dependencies
pip install .
```
### 2. Start the Visual Web Client
Run the following command to start the visual AI assistant page:
```bash
smartoffice-client
```
After starting, open a browser and visit `http://127.0.0.1:8000`. Fill in the API Key in the top-right system settings, select the recommended **Gemini 3.5 Flash** or **GPT-4o**, and you're ready to start office automation!
### 3. Access Client as a Standard MCP Server
If you're using Claude Desktop, Cursor, or other MCP-compatible clients, add the following to their configuration files (e.g., `claude_desktop_config.json`):
```json
{
"mcpServers": {
"smartoffice-mcp": {
"command": "python",
"args": ["-m", "smartoffice_mcp.gateway"]
}
}
}
```
## Project Structure
```text
smartoffice-mcp/
├── src/smartoffice_mcp/
│ ├── gateway.py # MCP standard gateway and tool routing definition
│ ├── client_web/ # FastAPI visual client backend and static pages
│ ├── engines/ # Excel / Word / PDF core automation processing engine
│ └── utils/ # Sandbox path verification and public tools
├── pyproject.toml # Project configuration and dependency package list
├── LICENSE # MIT open-source license
└── README.md # Project documentation
```
## Open-Source License
This project uses the [MIT License](LICENSE) open-source license.
