Aspose.Words MCP Server is an MCP (Model Context Protocol) 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.

Features

Aspose.Words MCP Server supports the following features:

  • Create documents; read/write text, headings, and paragraphs
  • 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
  • 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)
  • Protection: protect/unprotect, partial editing restrictions
  • Bookmarks, hyperlinks
  • Watermarks (text/image)
  • Export as Base64 (DOCX, PDF, etc.), advanced export options
  • Render page to image (PNG, etc.)
  • In‑memory document management: copy, save as, list, delete, merge

How to Install Aspose.Words MCP Server

To install Aspose.Words MCP Server via pip, run the following:

pip install aspose-words-mcp

To install Aspose.Words MCP Server from source, run the following:

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

How to Run Aspose.Words MCP Server

After installation, use this CLI command:

aspose-words-mcp

Without installation, run the following:

python mcp_server.py

By default, the server runs with the stdio transport.

HTTP/SSE 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.

Aspose.Words License

The Aspose.Words license is applied on server startup. The path is resolved with the following precedence:

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

The following code example shows how to apply the license:

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

Tools Overview

Tool categories exposed by the server include:

  • 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
  • Watermarks: text and image watermarks
  • Links/bookmarks: hyperlinks and bookmarks
  • Properties: document properties
  • Protection: protection and restrictions
  • Comments/notes: comments, footnotes/endnotes
  • Export/render: export to formats and page rendering

For signatures and details, see the server source and tests in the repository (mcp_server.py, tests/features/*).

Integration Capabilities

Aspose.Words MCP Server supports the following integration options:

  • 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.

FAQ

  1. Q: How do I apply an Aspose.Words license to the MCP server?
    A: Set the ASPOSE_WORDS_LICENSE_PATH environment variable to the full path of your .lic file before starting the server, or pass the path via the license_path argument of run_server(...). The server will load the license on startup; if the file is missing or invalid, it runs in evaluation mode.

  2. Q: How can I change the transport used by the MCP server?
    A: Define the MCP_TRANSPORT environment variable with one of the supported values: stdio, streamable-http, or sse. The server reads this variable at launch and configures the corresponding transport automatically.

  3. Q: How do I run the MCP server on a custom host and port?
    A: Use the MCP_HOST and MCP_PORT environment variables to specify the desired address and port, e.g., export MCP_HOST=127.0.0.1 and export MCP_PORT=9090 before starting the server.

  4. Q: What should I do if the server fails to start because the license is reported as invalid?
    A: Verify that the license file is a valid Aspose.Words for Python via .NET license (not an Aspose.Total.NET.lic file), ensure the path is correct, and confirm that the license matches the product version. If the license is correct, restart the server; otherwise, the server will operate in evaluation mode.

  5. Q: Can I use an Aspose.Total.NET.lic file with the MCP server for Python?
    A: No. The MCP server requires a license specifically for Aspose.Words for Python via .NET. An Aspose.Total.NET.lic does not cover this product, so you need to obtain a separate Aspose.Words license.

Getting Started AI-powered Features