# What's Spire.Doc MCP Server ?

Spire.Doc MCP Server is a Model Context Protocol (MCP) server that enables you to manipulate Word documents without requiring Microsoft Word. With it, you can [create](https://www.e-iceblue.com/Tutorials/Python/Spire.Doc-for-Python/Program-Guide/Document-Operation/Python-Create-Word-Document.html), [read](https://www.e-iceblue.com/Tutorials/Python/Spire.Doc-for-Python/Program-Guide/Document-Operation/read-word-doc-or-docx-files-in-python.html), and [modify](https://www.e-iceblue.com/Tutorials/Python/Spire.Doc-for-Python/Program-Guide/Document-Operation/Python-Edit-or-Modify-a-Word-Document.html) Word documents directly using your AI agent.


## Key Features

- [Create Word documents from Scratch](https://www.e-iceblue.com/Tutorials/Python/Spire.Doc-for-Python/Program-Guide/Document-Operation/Python-Create-Word-Document.html)
- [Modify existing Word files](https://www.e-iceblue.com/Tutorials/Python/Spire.Doc-for-Python/Program-Guide/Document-Operation/Python-Edit-or-Modify-a-Word-Document.html)
- Convert [Word to PDF](https://www.e-iceblue.com/Tutorials/Python/Spire.Doc-for-Python/Program-Guide/Conversion/Python-Convert-Word-to-PDF.html), [Word to Images](https://www.e-iceblue.com/Tutorials/Python/Spire.Doc-for-Python/Program-Guide/Conversion/Python-Convert-Word-to-Images.html), and more with high fidelity
- [Read](https://www.e-iceblue.com/Tutorials/Python/Spire.Doc-for-Python/Program-Guide/Document-Operation/read-word-doc-or-docx-files-in-python.html) and [write document content](https://www.e-iceblue.com/Tutorials/Python/Spire.Doc-for-Python/Program-Guide/Document-Operation/Python-Create-Word-Document.html/)
- Apply formatting and styles
- Analyze document content
- [Table operations and management](https://www.e-iceblue.com/Tutorials/Python/Spire.Doc-for-Python/Program-Guide/Table/Python-Create-Tables-in-a-Word-Document.html)
- [Paragraph manipulation and formatting](https://www.e-iceblue.com/Tutorials/Python/Spire.Doc-for-Python/Program-Guide/Document-Operation/Python-Create-Word-Document.html#4)
- [Document protection and security](https://www.e-iceblue.com/Tutorials/Python/Spire.Doc-for-Python/Program-Guide/Security/Python-Encrypt-or-Decrypt-Word-Documents.html)
- [Document comparison](https://www.e-iceblue.com/Tutorials/Python/Spire.Doc-for-Python/Program-Guide/Document-Operation/Python-Compare-Two-Versions-of-a-Word-Document.html) and [merging](https://www.e-iceblue.com/Tutorials/Python/Spire.Doc-for-Python/Program-Guide/Document-Operation/Python-Merge-Word-Documents.html)
- [Text watermark](https://www.e-iceblue.com/Tutorials/Python/Spire.Doc-for-Python/Program-Guide/Watermark/Python-Insert-Watermarks-in-Word.html) support

## Quick Start

### Prerequisites

- Python 3.10 or higher

### Installation

1. Clone the repository:

```bash
git clone https://github.com/eiceblue/spire-doc-mcp-server.git
cd spire-doc-mcp-server
```

2. Install using uv:

```bash
uv pip install -e .
```

### Running the Server

Start the server (default port 8000):

```bash
uv run spire-doc-mcp-server
```

Custom port (e.g., 8080):

```bash
# Bash/Linux/macOS
export SPIRE_DOC_MCP_PORT=8080 && uv run spire-doc-mcp-server

# Windows PowerShell
$env:SPIRE_DOC_MCP_PORT = "8080"; uv run spire-doc-mcp-server
```

## Integration with AI Tools

### Cursor IDE

1. Add this configuration to Cursor:

```json
{
  "mcpServers": {
    "word": {
      "url": "http://localhost:8000/sse",
      "env": {
        "WORD_FILES_PATH": "/path/to/word/files"
      }
    }
  }
}
```

2. The Word tools will be available through your AI assistant.

## Environment Variables

| Variable | Description | Default |
|--------|------|--------|
| `WORD_FILES_PATH` | Directory for Word files | `./word_files` |

## Available Tools

The server provides **18 tools** organized into 5 categories:

### Document Operations (6 tools)

- **create_document**: Create new Word documents with optional templates
- **set_document_protection**: Apply password protection to documents
- **find_and_replace**: Search and replace text in documents
- **merge_documents**: Merge multiple documents into one
- **add_text_watermark**: Add text watermarks to documents

### Paragraph Operations (5 tools)

- **get_paragraph_text**: Retrieve text content from paragraphs
- **delete_paragraph**: Remove paragraphs from documents
- **get_paragraph_info**: Get detailed paragraph information
- **add_paragraph**: Add new paragraphs to documents
- **update_paragraph_text**: Modify paragraph text content

### Table Operations (6 tools)

- **create_table**: Create new tables with specified dimensions
- **add_table_after_paragraph**: Insert tables after specific paragraphs
- **add_table_to_section**: Add tables to the end of sections
- **get_table_info**: Get table information and structure
- **delete_table**: Remove tables from documents
- **set_cell_text**: Set text content in table cells

### Formatting Operations (2 tools)

- **format_paragraph**: Apply formatting to paragraphs (alignment, indentation, spacing)
- **get_paragraph_format**: Retrieve paragraph formatting information

### Conversion Operations (3 tools)

- **convert_document**: Convert documents between different formats
- **get_conversion_status**: Check conversion operation status
- **get_conversion_history**: View conversion history

## Supported Formats

### Input Formats

- **DOC**: Microsoft Word 97-2003 Document
- **DOCX**: Microsoft Word 2007+ Document
- **DOCM**: Microsoft Word 2007+ Macro-Enabled Document
- **DOT**: Microsoft Word 97-2003 Template
- **DOTX**: Microsoft Word 2007+ Template
- **DOTM**: Microsoft Word 2007+ Macro-Enabled Template

### Output Formats

- **DOC**: Microsoft Word 97-2003 Document
- **DOCX**: Microsoft Word 2007+ Document
- **[PDF](https://https://www.e-iceblue.com/Tutorials/Python/Spire.Doc-for-Python/Program-Guide/Conversion/Python-Convert-Word-to-PDF.html)**: Portable Document Format
- **[RTF](https://www.e-iceblue.com/Tutorials/Python/Spire.Doc-for-Python/Program-Guide/Conversion/Python-Convert-Word-to-RTF-and-Vice-Versa.html)**: Rich Text Format
- **[HTML](https://www.e-iceblue.com/Tutorials/Python/Spire.Doc-for-Python/Program-Guide/Conversion/Python-Convert-Word-to-HTML.html)**: HyperText Markup Language
- **[TXT](https://www.e-iceblue.com/Tutorials/Python/Spire.Doc-for-Python/Program-Guide/Conversion/Python-Convert-Text-to-Word-or-Word-to-Text.html)**: Plain Text
- **[EPUB](https://www.e-iceblue.com/Tutorials/Python/Spire.Doc-for-Python/Program-Guide/Conversion/Python-Convert-Word-to-EPUB.html)**: Electronic Publication
- **ODT**: OpenDocument Text
- **[XML](https://www.e-iceblue.com/Tutorials/Python/Spire.Doc-for-Python/Program-Guide/Conversion/Python-Convert-Word-to-XML-Word-XML.html)**: Extensible Markup Language
- **[Markdown](https://www.e-iceblue.com/Tutorials/Python/Spire.Doc-for-Python/Program-Guide/Conversion/Python-Convert-Markdown-to-Word-or-Word-to-Markdown.html)**: Markdown Format

## Development

### Project Structure

```
spire-doc-mcp-server/
├── src/spire_doc_mcp/
│   ├── api/                 # API layer (18 tools)
│   │   ├── document_tools.py
│   │   ├── paragraph_tools.py
│   │   ├── table_tools.py
│   │   ├── format_tools.py
│   │   └── conversion_tools.py
│   ├── core/               # Core business logic
│   │   ├── document.py
│   │   ├── paragraph.py
│   │   ├── table.py
│   │   ├── format.py
│   │   ├── conversion.py
│   │   └── base.py
│   ├── utils/              # Utilities and constants
│   │   ├── exceptions.py
│   │   └── constants.py
│   ├── server.py           # MCP server implementation
│   └── __main__.py         # Entry point
├── pyproject.toml          # Project configuration
├── README.md              # This file
└── TOOLS.md               # Detailed tool documentation
```

### Running Tests

```bash
uv run pytest
```

### Code Quality

The project follows Python best practices:

- Type hints throughout
- Comprehensive error handling
- Consistent code formatting
- Detailed documentation
- Modular architecture

## Documentation

- **[TOOLS.md](TOOLS.md)**: Comprehensive tool documentation with examples
- **[API Reference](TOOLS.md#detailed-tool-documentation)**: Detailed API documentation
- **[Error Handling](TOOLS.md#error-handling)**: Error codes and troubleshooting

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

For support and questions:

- Check the [TOOLS.md](TOOLS.md) documentation
- Review the error handling section
- Open an issue on GitHub

## Version History

- **v1.0.0**: Initial stable release with 18 tools
- Complete Word document manipulation capabilities
- Comprehensive error handling
- Full format conversion support