README.md

---
title: MCP Docx Tools
emoji: 🐠
colorFrom: purple
colorTo: red
sdk: gradio
sdk_version: 6.0.0
app_file: app.py
pinned: false
short_description: From LLMs read and create docx via MCP

tags:
  - building-mcp-track-enterprise
  - building-mcp-track-consumer
  - building-mcp-track-creative
  - mcp
  - word
  - document
  - reader
  - writer
  - mcp-1st-birthday
  - hackathon

---



# 📄 MCP Word Toolkit – Gradio Server (Reader/Writer)

![Project Character Mascot](character.png)



### 🎈 MCP 1st Birthday Hackathon

Demonstrating how *Model Context Protocol* connects LLMs with local and remote productivity tools.

## 🎥 Project Presentation

<video controls src=".\beta_docx_enhaced.mp4" width="100%"></video>

## 🔗 LinkedIn Showcase
Project demo post: https://www.linkedin.com/posts/oscar-felipe-gonz%C3%A1lez-gonz%C3%A1lez-019971387_mcp-artificialintelligence-hackathon-activity-7400155174138245121-DKiX

## ✨ Features

- 📖 **read_word**: Reads and extracts content from `.docx` files preserving paragraph breaks.
- ✍️ **create_word**: Creates a new Word document with the specified content (overwrites if it exists).
- 🌐 **Gradio + MCP**: Fast interface that also exposes tools as an MCP server for other clients.
- 🔌 **MCP Integration**: Automatic tool discovery in compatible copilots (`mcp_server=True`).
- 🛡️ **Configurable Security**: Limits system scope with `allowed_directories`.
- 💻 **Local / Remote**: Works fully local (edge) or as a remote HF Space endpoint.

## 🚀 Quick Start (Local)

```powershell
git clone <repo>
cd <repo>
pip install -r requirements.txt
python app.py
```


## 🌐 Remote MCP Endpoint

## 📡 Gradio MCP Server URL

```
https://mcp-1st-birthday-mcp-docx-tools.hf.space/gradio_api/mcp/
```

## ⚙️ Configuration for Claude Desktop / MCPHost

It is important to define `allowed_directories` to prevent unwanted access. Add only working folders, never the entire disk.

#### Option 1: JSON (for `claude_desktop_config.json`) (I haven't managed to make it work in Claude_server)

```json
{
  "mcpServers": {
    "word-docx-server": {
      "type": "remote",
      "url": "https://mcp-1st-birthday-mcp-docx-tools.hf.space/gradio_api/mcp/",
      "options": {
        "allowed_directories": []
      }
    }
  }
}
```

#### Option 2: YAML for

```yaml
mcpServers:
  word-docx-server:
    type: "remote"
    url: "https://mcp-1st-birthday-mcp-docx-tools.hf.space/gradio_api/mcp/"
    options:
      allowed_directories: []

````


#### Example Prompts
> "Read the file C:\\Docs\\report.docx, summarize in 5 bullet points and create C:\\Docs\\summary.docx with that content using the available tools."

> "Translate the content of C:\\Docs\\notes.txt to Spanish and save it as C:\\Docs\\notes_es.docx."

> "Create a document at C:\\Docs\\plan.docx with a 5-day travel itinerary to Tokyo."


## 🔧 MCP Tools Exposed

- `read_word` – Extract content from a Word file.
- `create_word` – Create a new Word document.

### Chaining Example
```
Use read_word on C:\Reports\2025_Q1.docx, summarize to 5 bullet points, then create_word to C:\Reports\2025_Q1_summary.docx with that summary.
```

## 🛡️ Security

- Limit `allowed_directories` to specific folders.
- Avoid documents with personal data if using remote services.
- Verify paths before generating content (overwrites without asking).

## 🧪 Troubleshooting

| Issue | Cause | Fix |
|-------|-------|-----|
| File not found | Incorrect path | Check separators and permissions |
| Empty output | Document with empty paragraphs | Normal if text is not specified |
| Corrupt docx | Damaged file | Open in Word and save again |

## 🛠️ Tech Stack

- Python 3.9+
- Gradio (`mcp_server=True` capability)
- python-docx
- Model Context Protocol


## 🙏 Acknowledgments

Special thanks to:

- **Hugging Face** for hosting and platform support.
- **Google**  for video generation tools(Veo 3.1) and Antigravity with gemini 3 Pro (Preview).
- **Anthropic** for Claude Server.

<div align="center">
  <img src="https://huggingface.co/front/assets/huggingface_logo-noborder.svg" alt="Hugging Face" height="50" style="margin: 0 20px;" />
  <img src="https://upload.wikimedia.org/wikipedia/commons/2/2f/Google_2015_logo.svg" alt="Google" height="50" style="margin: 0 20px;" />
  <img src="https://upload.wikimedia.org/wikipedia/commons/7/78/Anthropic_logo.svg" alt="Anthropic" height="50" style="margin: 0 20px;" />
</div>

## ⚠️ Disclaimer

A large part of the content of this project has been created with AI tools.

## 📝 License

Apache License 2.0 

---

Made with ❤️ for the MCP-1st-Birthday Hackathon. Contributions & issues welcome.