MCP-OPENAPI-DOCX

You can run, manage, and extend this MCP server to edit and process DOCX documents using the Model Context Protocol. It exposes OpenAPI endpoints for document operations and an MCP endpoint for AI-driven workflows, allowing you to edit, format, export, and track changes in DOCX files at scale.

How to use

You interact with the server through an MCP client and through the OpenAPI REST endpoints. Use MCP to call tools like create_document, add_paragraph, add_table, format_text, and export_document to build and modify DOCX documents. Use the REST API to list, create, retrieve, update, and delete documents, and to manage text, tables, formatting, and exports. Start the MCP server to enable AI integrations and then connect your MCP client to the provided MCP URL or local stdio entry as described in the installation steps.

How to install

Prerequisites: you need Python 3.10 or higher and Docker/Docker Compose if you plan to run containers. Redis is recommended for background tasks, and PostgreSQL can be used for production databases (SQLite is available for development).

# Create and activate a virtual environment
python -m venv venv

# On Linux/macOS
source venv/bin/activate

# On Windows (Command Prompt)
venv\Scripts\activate.bat

# On Windows (PowerShell)
venv\Scripts\Activate.ps1

# Upgrade pip
pip install --upgrade pip

# Install dependencies
pip install -r requirements.txt

# Copy environment configuration (adjust as needed)
cp .env.example .env

# Run the application (start API and MCP capable server)
python main.py

Additional setup and starting the MCP server

To enable AI integrations, start the MCP server component alongside the API. The final command to start the MCP-enabled server is shown here.

# Start MCP server mode for AI integrations
python main.py --mcp

Configuration notes

Configuration is primarily environment-driven. Copy the example environment file to .env and adjust values such as DATABASE_URL, REDIS_URL, SECRET_KEY, and upload settings to fit your deployment.

MCP configuration example

If you want to explicitly register the local MCP entry, you can provide a configuration snippet that points to the local runtime.

{
  "mcpServers": {
    "mcp_openapi": {
      "command": "python",
      "args": ["main.py", "--mcp"]
    }
  }
}

Troubleshooting notes

• Ensure Python 3.10+ is active in your environment when starting the server. - Check that Redis is reachable if you expect background tasks to run. - Validate that the upload directory exists and has proper permissions. - Review startup logs for any missing environment variables and add them to .env as needed.

Security and exports

The server supports encryption and password protection for documents, along with access permissions. Use the export options to convert DOCX documents to PDF, HTML, Markdown, or plain text while preserving formatting and revisions.

Development and testing notes

For development, use a virtual environment, run linting and type checks, and execute tests regularly. Development server startup can be done with the same command shown above, and you can also run the app with auto-reload for rapid iteration.

Deployment tips

Containerized deployment is supported. Use Docker Compose for development and Kubernetes for production deployments. Start with docker-compose up -d and then scale workers as needed for background tasks.

Notes on usage patterns

• Use the MCP protocol for AI-driven document operations and the REST API for standard document management. - Leverage version control and templates to maintain consistency across documents. - Use the export features to generate portable formats for distribution and archiving.

License and support

The project uses an MIT-style license. For support, use the designated channels for issues and discussions related to the MCP server features.

Available tools

create_document

Create a new DOCX document with a given name and initial content.

open_document

Open and load an existing DOCX document for editing.

add_paragraph

Add a paragraph to a document, with optional formatting and style.

add_table

Add a table to a document and populate it with rows and cells.

format_text

Apply formatting to selected text or blocks, such as bold, italic, or heading styles.

search_replace

Search for text within a document and replace it with new content.

export_document

Export the document to PDF, HTML, Markdown, or plain text.

comment/revisions

Add comments and track changes to a document per user actions.