Aspose.Words MCP

Overview

Aspose.Words MCP is a FastMCP-based MCP server built on top of Aspose.Words for Python via .NET. It automates Microsoft Word document creation and editing and exposes operations as MCP tools that any MCP-compatible client can call. The server is aligned with Aspose.Words for Python via .NET 26.10.0. Supported transports: stdio, streamable-http, sse.

Features

• Create documents; read/write text, headings, and paragraphs
• Text replacement workflows, including optional run joining when needed
• Text formatting (font, size, style, color, underline)
• Page and section breaks; page setup (margins, orientation, paper size, columns)
• Lists (bulleted/numbered)
• Tables: create, auto-fit, merge cells, alignment, shading, paddings, column widths, header styling
• Charts: create column and waterfall charts, list charts, format plot-area fills and lines, inspect waterfall totals
• Footnotes and endnotes: add, convert, anchor-based operations, validation
• Comments: get by author, by paragraph, all comments
• Document properties: read/write (title, author, subject, keywords)
• Document comparison with revision output
• Protection: protect/unprotect, partial editing restrictions
• Digital signatures: sign documents with optional timestamp settings and inspect signature metadata
• Bookmarks, hyperlinks
• Watermarks (text/image)
• Export as Base64 (DOCX, signed PDF, XPS, etc.)
• Render page to image (PNG, etc.)
• In-memory document management: copy, save as, list, delete, merge

Requirements

• Python 3.11+
• Aspose.Words for Python via .Net. This library is a commercial product.

You'll need to obtain a valid license for Aspose.Words. The package will install this dependency, but you're responsible for complying with Aspose's licensing terms.

Installation

pip install aspose-words-mcp

From source (download repo and install requirements):

git clone https://github.com/aspose-words/Aspose.Words-MCP
cd Aspose.Words-MCP
pip install -r requirements.txt

Command Line Interface

After installation, the CLI command is available:

aspose-words-mcp

By default, the server runs with the stdio transport.

Run without installation:

python mcp_server.py

Transports and Configuration

Supported MCP transports: stdio, streamable-http, sse.

Environment Variables

• MCP_TRANSPORT — stdio | streamable-http | sse (default stdio)
• MCP_HOST — host address (default 0.0.0.0)
• MCP_PORT — port (default 8080)
• MCP_PATH — HTTP path for streamable-http (default /mcp)
• MCP_SSE_PATH — events path for sse (default /sse)
• LOG_LEVEL — logging level (INFO, DEBUG, ...)

Aspose.Words License

The Aspose.Words license is applied when the server starts. The effective path to the license file is resolved with the following precedence:

1) The license_path argument of run_server(..., license_path=None) 2) The ASPOSE_WORDS_LICENSE_PATH environment variable

If no license is provided or the file is not accessible, the server runs in Evaluation mode.

Example of setting the environment variable:

export ASPOSE_WORDS_LICENSE_PATH='/path/to/aspose.words.lic'

HTTP/SSE Run Example

export MCP_TRANSPORT=streamable-http   # or sse
export MCP_HOST=0.0.0.0
export MCP_PORT=8080
export MCP_PATH=/mcp                   # for streamable-http
export MCP_SSE_PATH=/sse               # for sse
aspose-words-mcp

On start, the server prints the listening address.

Development Validation

Install development dependencies with python -m pip install -e '.[dev]', then run:

python -m pytest -q
python -m ruff check .
python -m ruff format . --check
python -m pyright --pythonpath .venv/bin/python

All four checks are required before merging a server update.

Tools

See full list and signatures in mcp_server.py (function register_tools) and tests in tests/features/*.

Main tool categories:

• content/reading: create document, insert/delete/read text, headings, lists, HTML/Markdown
• layout: pages, breaks, columns, headers/footers, page numbering
• tables: create and format tables
• charts: add_chart_end, list_charts, format_chart_plot_area, get_waterfall_totals
• watermarks: watermarks
• links/bookmarks: hyperlinks and bookmarks
• properties: document properties
• comparison: compare documents and save revisions
• protection: protection and restrictions
• signatures: signing and signature metadata
• comments/notes: comments, footnotes/endnotes
• export/render: export (including Docling, signed PDF, and XPS advanced export), page rendering

Use add_chart_end with chart_type="column" or "waterfall", a shared categories list, and series objects containing name and numeric values matching the categories. Waterfall series also require a matching is_subtotal boolean array. Use the zero-based chartIndex and seriesIndex values from list_charts to select charts and series. format_chart_plot_area accepts a solid fill_color or a one-color gradient object, plus optional line_color and line_width_points; colors use six-digit RGB hex, and omitted formatting fields retain their values. get_waterfall_totals inspects all points in the selected waterfall series, or a single zero-based point_index.

Example Workflow via an MCP Client

Sequence of tool calls (names match the server):

1. create_document → get doc_id
2. add_heading (e.g., levels 1–3)
3. add_paragraph / insert_text_end
4. add_table_end or add_table_at_paragraph
5. add_watermark_text or add_watermark_image_base64
6. export_base64 (e.g., fmt="pdf") — get file as Base64

Integration with MCP Clients

• Claude Desktop MCP: add this server with streamable-http or sse transport and the URL printed by the server at startup.
• Any MCP (JSON) clients — configure the matching transport and path.

License

This package is licensed under the MIT License. However, it depends on Aspose.Words for Python via .Net library, which is proprietary, closed-source library.

⚠️ You must obtain valid license for Aspose.Words for Python via .Net library. This repository does not include or distribute any proprietary components.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Use of third-party trademarks or logos is subject to those third-party policies.