word-mcp 1.0.3

A Model Context Protocol server for Microsoft Word integration

Word MCP Server

A powerful Model Context Protocol (MCP) server for Microsoft Word integration, enabling AI assistants and automation tools to interact with Word documents across Windows and macOS platforms.

🚀 Features

• Cross-platform Support: Works on both Windows and macOS
• Document Automation: Read, write, and manipulate Word documents programmatically
• AI-Powered Workflows: Perfect for document translation, content generation, and editing
• Section-by-Section Processing: Systematically process documents paragraph by paragraph
• State Management: Intelligent tracking of processed content to avoid infinite loops
• Multiple Word Instances: Support for multiple Word documents simultaneously

📦 Installation

pip install word-mcp

Platform-Specific Requirements

Windows:

• Microsoft Word (part of Microsoft Office)
• pywin32 (automatically installed)

macOS:

• Microsoft Word (part of Microsoft Office)
• AppleScript support (built into macOS)

🛠️ Quick Start

1. Using uvx (Recommended)

Run the server directly without installing:

# Using the main command
uvx wordmcp

# Or the alternative command name
uvx word-mcp

# When published to PyPI, you can also use:
# uvx word-mcp

For development or local testing with a wheel file:

# Build the package first
python -m build

# Run with local wheel
uvx --from ./dist/word_mcp-1.0.0-py3-none-any.whl wordmcp

2. Command Line Usage (After Installation)

Install and run the MCP server:

pip install word-mcp
word-mcp
# or
wordmcp

3. Module Usage

Run as a Python module:

python -m word_mcp

4. Programmatic Usage

import asyncio
from word_mcp import create_server, run_server

# Create a server instance
server = create_server("my-word-server")

# Or run the server directly
run_server("my-word-server")

3. Integration with AI Assistants

The server exposes the following MCP tools that AI assistants can use:

• get_selection_text - Get currently selected text
• replace_selection_text - Replace selected text with new content
• select_next_section - Move to the next document section
• find_and_select_section - Find and select text by keywords
• list_word_instances - List all open Word documents

📖 Use Cases

Document Translation

Perfect for section-by-section translation workflows:

# AI assistant workflow:
# 1. select_next_section() -> finds next untranslated paragraph
# 2. get_selection_text() -> gets the content
# 3. [AI translates the text]
# 4. replace_selection_text() -> replaces with translation
# 5. Repeat until document is fully translated

Content Generation

Automate content creation and editing:

• Generate documentation from templates
• Apply consistent formatting across documents
• Bulk content updates and modifications

Document Analysis

Extract and analyze document content:

• Parse document structure
• Extract specific sections or data
• Generate summaries and reports

🔧 API Reference

Tools Available via MCP

get_selection_text

Retrieves the currently selected text from the active Word document.

Parameters:

• instance_id (optional): Target specific Word instance

Returns:

{
  "text": "Selected content...",
  "instance_id": "word-instance-1"
}

replace_selection_text

Replaces the currently selected text with new content.

Parameters:

• text: New text to insert
• instance_id (optional): Target specific Word instance

Returns:

{
  "success": true,
  "instance_id": "word-instance-1"
}

select_next_section

Finds and selects the next section in the document.

Parameters:

• section_type: Type of section ("paragraph", "heading", "any")
• instance_id (optional): Target specific Word instance

Returns:

{
  "found": true,
  "section_text": "Next section content...",
  "section_type": "paragraph",
  "instance_id": "word-instance-1"
}

find_and_select_section

Finds and selects a section containing specific keywords.

Parameters:

• keywords: Keywords to search for
• section_type: Type of section to search in
• instance_id (optional): Target specific Word instance

list_word_instances

Lists all currently running Word instances.

Returns:

{
  "instances": [
    {
      "instance_id": "word-instance-1",
      "document_title": "Document1.docx",
      "is_active": true
    }
  ]
}

🔒 Security & Permissions

Windows

• Requires Microsoft Word to be installed and accessible
• Uses COM automation (requires appropriate permissions)

macOS

• Requires Microsoft Word to be installed
• Uses AppleScript (may require accessibility permissions for some operations)
• Grant permissions in System Preferences > Security & Privacy > Privacy > Accessibility

🐛 Troubleshooting

Common Issues

"No Word instances found"

• Ensure Microsoft Word is running
• Check that Word documents are open

"Platform not supported"

• Currently supports Windows and macOS only
• Linux support may be added in future versions

AppleScript permission errors (macOS)

• Grant accessibility permissions to your terminal/IDE
• System Preferences > Security & Privacy > Privacy > Accessibility

Debug Mode

Enable detailed logging:

import logging
logging.basicConfig(level=logging.DEBUG)

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/word-mcp/word-mcp.git
cd word-mcp
pip install -e ".[dev]"

Running Tests

pytest tests/

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built on the Model Context Protocol
• Inspired by the need for better AI-document integration
• Thanks to the Microsoft Office automation community

📞 Support

• 📫 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

---

Made with ❤️ for the AI automation community