https://github.com/xjustloveux/aspose-mcp-server
Aspose MCP Server - MCP 辦公文檔處理服務器 為 AI 助手提供辦公文檔處理工具。支援 Word、Excel、PowerPoint、PDF 及跨格式轉換。按需啟用、跨平台（Windows/Linux/macOS）、開箱即用。從 Releases 下載預編譯版本，配置授權檔案即可使用。
https://github.com/xjustloveux/aspose-mcp-server
ai-tools aspose excel mcp office pdf powerpoint ppt word
Last synced: about 2 months ago
JSON representation
Aspose MCP Server - MCP 辦公文檔處理服務器 為 AI 助手提供辦公文檔處理工具。支援 Word、Excel、PowerPoint、PDF 及跨格式轉換。按需啟用、跨平台（Windows/Linux/macOS）、開箱即用。從 Releases 下載預編譯版本，配置授權檔案即可使用。
- Host: GitHub
- URL: https://github.com/xjustloveux/aspose-mcp-server
- Owner: xjustloveux
- License: mit
- Created: 2025-12-10T16:25:24.000Z (6 months ago)
- Default Branch: master
- Last Pushed: 2026-04-17T07:24:49.000Z (about 2 months ago)
- Last Synced: 2026-04-17T08:22:30.580Z (about 2 months ago)
- Topics: ai-tools, aspose, excel, mcp, office, pdf, powerpoint, ppt, word
- Language: C#
- Homepage: https://xjustloveux.github.io/aspose-mcp-server/
- Size: 11.7 MB
- Stars: 14
- Watchers: 0
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Aspose MCP Server
[](https://github.com/xjustloveux/aspose-mcp-server/releases)
[](LICENSE)
[](https://dotnet.microsoft.com/)
[](https://github.com/xjustloveux/aspose-mcp-server/actions/workflows/build-multi-platform.yml)
[](https://github.com/xjustloveux/aspose-mcp-server/actions/workflows/test.yml)
[](https://codecov.io/gh/xjustloveux/aspose-mcp-server)
[](https://sonarcloud.io/summary/new_code?id=xjustloveux_aspose-mcp-server)
[](https://sonarcloud.io/summary/new_code?id=xjustloveux_aspose-mcp-server)
[](https://modelcontextprotocol.io/)
[](https://github.com/modelcontextprotocol/csharp-sdk)
[](https://xjustloveux.github.io/aspose-mcp-server/getting-started.html#mcpb)
[](https://products.aspose.com/total/net/)
[](https://xunit.net/)
**格式支援：**       
基於 .NET 8.0 和 Aspose.Total 的 Model Context Protocol (MCP) 伺服器，為 MCP 客戶端提供強大的辦公文檔處理能力。
## ✨ 特性
### 核心功能
- **118 個統一工具** - Word(28)、Excel(32)、PowerPoint(26)、PDF(19)、OCR(2)、Email(6)、BarCode(2)、轉換(1)、Session(1)、Extension(1) 已整合
- **按需啟用** - 只啟用需要的文檔類型，減少資源佔用
- **跨平台** - Windows、Linux、macOS (Intel + ARM)，單一可執行檔案
- **開箱即用** - 預編譯版本無需安裝 .NET Runtime
- **完整讀寫** - 支援從A文檔讀取格式應用到B文檔
### 傳輸模式
- **Stdio 模式** (預設) - 標準輸入輸出，適用於本地 MCP 客戶端
- **HTTP 模式** - Streamable HTTP（MCP 2025-03-26+），適用於網頁應用
- **WebSocket 模式** - 雙向通訊，適用於即時互動
### 進階功能
- **Session 管理** - 在記憶體中編輯文件，支援 open/save/close 操作，支援多租戶隔離
- **擴充功能系統** - 外部程序訂閱 Session 變更，實現即時預覽、雲端同步、合規檢查等
- **認證機制** - 可選的 API Key 和 JWT 認證（4 種驗證模式）
- **追蹤系統** - 結構化日誌、Webhook 通知、Prometheus Metrics
- **Origin 驗證** - 防止 DNS 重綁定攻擊（HTTP/WebSocket 模式）
### 技術特性
- **MCP SDK 1.2.0** - 使用官方 ModelContextProtocol NuGet 套件，支援 Tool Annotations 和 outputSchema
- **Tool Annotations** - 所有工具標註 ReadOnly、Destructive、Idempotent、OpenWorld 行為特性
- **結構化輸出** - Handler 返回強型別結果，SDK 自動生成 outputSchema（oneOf JSON Schema）
- **統一字型設定** - 多個工具支援中英文字型分別設定（`fontNameAscii` 和 `fontNameFarEast` 參數）
- **靈活的授權配置** - 支援總授權或單一組件授權，自動搜尋、環境變數或命令列參數配置
- **安全加固** - 全面的路徑驗證、輸入驗證和錯誤處理
## 🚀 快速開始
### 1. 下載
**方法 A：從 GitHub Releases 下載**
從 [GitHub Releases](https://github.com/xjustloveux/aspose-mcp-server/releases) 下載對應平台版本：
| 平台 | 檔案 |
|------|------|
| Windows | `aspose-mcp-server-windows-x64.zip` |
| Linux | `aspose-mcp-server-linux-x64.tar.gz` |
| macOS Intel | `aspose-mcp-server-macos-x64.tar.gz` |
| macOS ARM | `aspose-mcp-server-macos-arm64.tar.gz` |
**方法 B：macOS 使用 Homebrew 安裝（推薦）**
```bash
brew install xjustloveux/tap/aspose-mcp-server
```
### 2. 配置 MCP 客戶端
```json
{
"mcpServers": {
"aspose-word": {
"command": "C:/Tools/aspose-mcp-server/AsposeMcpServer.exe",
"args": ["--word"]
}
}
}
```
**可用參數**（不帶任何工具參數時，預設啟用所有工具）:
- `--word` - Word 工具（自動包含轉換功能）
- `--excel` - Excel 工具（自動包含轉換功能）
- `--powerpoint` / `--ppt` - PowerPoint 工具（自動包含轉換功能）
- `--pdf` - PDF 工具
- `--ocr` - OCR 文字辨識工具
- `--email` - Email 工具
- `--barcode` - BarCode 工具
- `--all` - 所有工具（等同不帶工具參數）
- `--session-enabled` - 啟用 Session 管理（`document_session` 工具）
- `--extension-enabled` - 啟用擴充功能系統（需搭配 `--session-enabled`）
- `--extension-config 路徑` - 指定擴充功能配置檔案路徑（`extension` 工具）
- `--license 路徑` - 指定授權檔案路徑（可選）
- `--allowed-path 路徑` - 限制檔案存取於指定基礎目錄下（可重複指定；未指定則不限制，建議在 HTTP/WebSocket 部署時啟用）
> **工具過濾**：指定工具參數時，只有啟用的工具類別會出現在 MCP 工具列表中。例如使用 `--word` 時，只會顯示 `word_*` 相關工具。
**轉換功能說明**：
- 啟用任何文檔工具（`--word`、`--excel`、`--ppt`、`--pdf`）時，自動包含 `convert_document`（跨格式轉換，支援 Word/Excel/PDF 轉圖片、特殊格式轉 PDF）
📋 **更多配置範例：** `config_example.json`（配置格式適用於所有 MCP 客戶端）
### 3. 重啟 MCP 客戶端
完成配置後，重啟您使用的 MCP 客戶端（如 Claude Desktop、Cursor 等）即可開始使用。
## 🖥️ Claude Desktop Extension (.mcpb)
Claude Desktop 使用者可將 Aspose MCP Server 以原生擴充功能安裝，繞過 Linux 沙箱限制，讓 Windows 路徑（`C:\Users\...`）直接可用。
| 平台 | 檔案 |
|------|------|
| Windows x64 | `aspose-mcp-server-windows-x64.mcpb` |
| macOS ARM64 | `aspose-mcp-server-macos-arm64.mcpb` |
| macOS x64 | `aspose-mcp-server-macos-x64.mcpb` |
| Linux x64 | `aspose-mcp-server-linux-x64.mcpb` |
**三步驟安裝：**
1. 從 [GitHub Releases](https://github.com/xjustloveux/aspose-mcp-server/releases) 下載對應平台的 `.mcpb` 檔案。
2. 雙擊檔案 — Claude Desktop 會開啟安裝對話框。
3. 依提示選擇 `Aspose.Total.lic` 授權檔；若跳過則以評估模式執行（輸出文件將帶有 Aspose 浮水印）。
> macOS 使用者：Claude Desktop 會自動處理隔離標記，**無需**手動執行 `xattr` 指令。
>
> 非 Claude Desktop 客戶端（Cursor、Continue 等）請使用 `.zip` / `.tar.gz` 安裝方式，詳見 [快速開始](https://xjustloveux.github.io/aspose-mcp-server/getting-started.html)。
## 📦 功能概覽
| 模組 | 工具數 | 主要功能 |
|------|--------|---------|
| **Word** | 28 | 檔案操作、文字/段落/表格/圖片/OLE編輯、格式/樣式/頁面設定、書籤/超連結/註釋/目錄/修訂/郵件合併/數位簽章/內容控制項/渲染 |
| **Excel** | 32 | 檔案/工作表/行列/單元格操作、排序/篩選/驗證、圖表/公式/樞紐分析、表格/形狀/OLE/迷你圖/JSON匯入/渲染 |
| **PowerPoint** | 26 | 檔案/投影片管理、文字/圖片/表格/圖表/形狀/SmartArt/OLE/媒體、動畫/轉場/備註/註解/加密/浮水印/字型管理 |
| **PDF** | 19 | 檔案操作（含加密/解密）、文字/圖片/表格/水印/頁面（含裁切）、書籤/註釋/表單（含匯入匯出）、頁首頁尾/印章/目錄/PDF/A合規 |
| **OCR** | 2 | 影像前處理（校正/降噪/對比/縮放）、文字辨識（圖片/PDF/收據/身分證/護照） |
| **Email** | 6 | 郵件建立/讀取/轉換、內容編輯、附件管理、日曆事件、聯絡人、格式轉換（EML↔MSG↔HTML） |
| **BarCode** | 2 | 條碼產生（QR/Code128/EAN13 等）、條碼辨識（自動偵測/指定類型） |
| **轉換** | 1 | `convert_document`（跨格式轉換：Word/Excel/PDF→圖片、HTML/EPUB/Markdown/SVG→PDF） |
| **Extension** | 1 | 擴充功能管理（list/bind/unbind/status/set_format/bindings/command），即時文檔快照推送 |
> 📖 完整工具列表與操作說明請參閱 [工具列表](https://xjustloveux.github.io/aspose-mcp-server/tools.html)
## 🔌 傳輸模式
| 模式 | 命令 | 端點 | 適用場景 |
|------|------|------|---------|
| **Stdio**（預設） | `AsposeMcpServer.exe --word` | - | 本地 MCP 客戶端 |
| **HTTP** | `AsposeMcpServer.exe --http --port 3000 --word` | `http://localhost:3000/mcp` | 網頁應用 |
| **WebSocket** | `AsposeMcpServer.exe --ws --port 3000 --word` | `ws://localhost:3000/mcp` | 即時互動 |
**環境變數：**
| 變數 | 說明 | 預設值 |
|------|------|--------|
| `ASPOSE_TRANSPORT` | 傳輸模式 (stdio/http/ws) | stdio |
| `ASPOSE_PORT` | 監聽埠號 | 3000 |
| `ASPOSE_HOST` | 監聽位址（`localhost`、`0.0.0.0`、`*`） | localhost |
| `ASPOSE_TOOLS` | 啟用的工具（all 或 word,excel,pdf,ppt,ocr,email,barcode） | 全部啟用 |
> **注意**: Docker/Kubernetes 部署時需設定 `ASPOSE_HOST=0.0.0.0` 以便容器外部可以訪問。
## 🔒 安全特性
- **路徑驗證** - 所有檔案路徑經 `SecurityHelper.ValidateFilePath()` 驗證，防止路徑遍歷攻擊；額外拒絕控制字元、NTFS Alternate Data Stream 冒號語法、路徑段末尾點號/空白、及 Windows 保留裝置名稱（CON/NUL/COM1–9 等）；符號連結（symbolic link）在任何 I/O 操作前均會解析至最終目標，並再次比對白名單，確保符號連結無法繞過路徑限制
- **路徑白名單**（可選強化）- 透過 `--allowed-path` 限制檔案存取於指定基礎目錄下（可重複指定）；未設定時不限制，建議 HTTP/WebSocket 部署時啟用；符號連結的最終目標若位於白名單之外，將被拒絕
- **輸入驗證** - 陣列大小上限 1000 項、字串長度上限 10000 字元
- **錯誤處理** - 結構化錯誤翻譯器（per-family translator 模式）將 Aspose/BCL 例外對應為固定安全哨兵字串；移除路徑、堆疊追蹤等敏感資訊，確保原始例外訊息不傳遞給呼叫方
- **Origin 驗證** - HTTP/WebSocket 模式預設啟用，防止 DNS 重綁定攻擊
| 限制項目 | 上限值 |
|---------|--------|
| 最大路徑長度 | 260 字元 |
| 最大檔案名稱長度 | 255 字元 |
| 最大陣列大小 | 1000 項 |
| 最大字串長度 | 10000 字元 |
> 📖 完整安全配置請參閱 [功能特性](https://xjustloveux.github.io/aspose-mcp-server/features.html)
## 🌍 跨平台支援
| 平台 | 文檔處理 | OCR | 備註 |
|------|---------|-----|------|
| Windows x64 | ✅ | ✅ | |
| Linux x64 | ✅ | ✅ | 不需要 libgdiplus |
| macOS Intel x64 | ✅ | ✅ | |
| macOS ARM64 (M1/M2/M3) | ✅ | ✅ | PPT/OCR 需 Rosetta 2 |
| Linux ARM64 | ✅ | ❌ | ONNX Runtime 限制 |
**跨平台方案：** PowerPoint 使用 `Aspose.Slides.NET6.CrossPlatform`、PDF 使用 `Aspose.PDF.Drawing`、Word/Excel 使用 `SkiaSharp`，全部無需外部圖形庫。
**Linux 字型：** 建議安裝 `fonts-liberation`（英文）和 `fonts-noto-cjk`（中日韓文），Docker 映像已內建基本 CJK 字型。
> 📖 詳細平台需求與字型配置請參閱 [部署指南](https://xjustloveux.github.io/aspose-mcp-server/deployment.html)
## 📄 授權
**本專案源代碼**採用 [MIT License](LICENSE) 授權。**運行時需要 Aspose 授權**，支援：
- `Aspose.Total.lic` - 總授權（包含所有組件，推薦）
- 單一組件授權：`Aspose.Words.lic`、`Aspose.Cells.lic`、`Aspose.Slides.lic`、`Aspose.Pdf.lic`、`Aspose.OCR.lic`、`Aspose.Email.lic`、`Aspose.BarCode.lic`
**配置方式（按優先順序）：**
1. **命令列參數**：`--license 路徑`
2. **環境變數**：`ASPOSE_LICENSE_PATH`
3. **自動搜尋**（預設）：在可執行檔案同一目錄搜尋
找不到授權時以試用模式運行（文檔含評估版標記）。使用 `test.ps1 -SkipLicense` 可在評估模式下運行測試。
## ⚠️ 重要說明
### 索引行為說明
**索引在刪除操作後會變化：**
- 當執行刪除操作（如刪除段落、表格、圖片等）後，後續元素的索引會自動調整
- **建議**：在執行刪除操作後，重新使用 `get` 操作獲取最新的索引列表
```
1. word_image(operation='get', path='doc.docx') # 返回圖片索引: 0, 1, 2
2. word_image(operation='delete', path='doc.docx', imageIndex=1) # 刪除索引1的圖片
3. word_image(operation='get', path='doc.docx') # 現在返回: 0, 1 (原索引2變成1)
```
**paragraphIndex 參數說明：**
- 有效範圍：`0` 到 `段落總數-1`，或使用 `-1` 表示最後一個段落
- 某些操作會在指定段落**之後**創建新段落，而不是插入到段落內部
**參數命名一致性：** 為向後兼容，某些參數支援多種命名（如 `startColumn` / `startCol`、`columnIndex` / `colIndex`）。
## 📝 使用範例
### 從A文檔複製格式到B文檔
**複製段落格式：**
```
1. word_paragraph(path="A.docx", operation="get_format", paragraphIndex=0)
2. 使用返回的格式資訊
3. word_paragraph(path="B.docx", operation="edit", paragraphIndex=0, ...)
```
**複製樣式：**
```
word_style(path="B.docx", operation="copy_styles", sourceDocument="A.docx")
```
## 🔗 相關資源
| 類別 | 連結 |
|------|------|
| **完整文檔** | [GitHub Pages](https://xjustloveux.github.io/aspose-mcp-server/) — 功能特性、工具列表、快速開始、開發者指南、部署指南、FAQ |
| **配置範例** | [config_example.json](config_example.json) · [extensions_example.json](extensions_example.json) |
| **Aspose** | [Aspose.Total for .NET](https://products.aspose.com/total/net/) |
| **MCP** | [MCP 官方網站](https://modelcontextprotocol.io/) · [.NET MCP SDK](https://github.com/modelcontextprotocol/csharp-sdk) |
| **MCP 客戶端** | [Claude Desktop](https://claude.ai/download) · [Cursor](https://cursor.sh/) · [Continue](https://continue.dev/) |
| **專案** | [GitHub Repository](https://github.com/xjustloveux/aspose-mcp-server) |
> 📖 進階主題（Session 管理、認證機制、追蹤系統、部署指南、開發者指南、常見問答）請參閱 [完整文檔](https://xjustloveux.github.io/aspose-mcp-server/)。