Hugging Face's logo

Spaces:
MCP-1st-Birthday
/
MCP_docx_tools
Sleeping

App Files Community
MCP_docx_tools
File size: 4,686 Bytes 
8834456
 
 
 
 
 
 
 
 
 
 
 
 
 
ffc6683
8834456
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5d8a8ea
8834456
e7b7975
 
 
8834456
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
d6eb476
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
 
---
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.