README.md

metadata

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)

🎈 MCP 1st Birthday Hackathon

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

🎥 Project Presentation

🔗 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)

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)

{
  "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

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.

⚠️ 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.