docx-mcp

# Quick Start Guide - docx-mcp Get the docx-mcp server up and running in 5 minutes. ## Prerequisites - Python 3.10 or higher - 100MB free disk space - macOS, Linux, or Windows ## Installation & Setup ### 1. Clone the repository ```bash cd docx-mcp ``` ### 2. Run the setup script ```bash ./setup.sh ``` This will: - Create a Python virtual environment - Install all dependencies via uv - Create necessary directories ### 3. Activate the environment ```bash source venv/bin/activate ``` ## Running the Server ### Option A: Use the run script ```bash ./run.sh ``` ### Option B: Use make ```bash make run ``` ### Option C: Direct command ```bash python -m docx_mcp.server ``` The server will start and listen for MCP connections. ## Using with Claude ### Step 1: Get your project path ```bash pwd # Copy this path ``` ### Step 2: Update Claude configuration Edit: `~/Library/Application Support/Claude/claude_desktop_config.json` Replace `/path/to/docx-mcp` with your actual path: ```json { "mcpServers": { "docx-mcp": { "command": "uv", "args": [ "--directory", "/path/to/docx-mcp", "run", "python", "-m", "docx_mcp.server" ] } } } ``` ### Step 3: Restart Claude Desktop ## Testing the Installation ### Run tests ```bash make test ``` ### Check specific functionality ```python # Create a test document from docx_mcp.server import create_docx, write_docx, read_docx filepath = "/tmp/test.docx" create_docx(filepath=filepath, title="My Document") write_docx(filepath=filepath, content="Hello, World!") result = read_docx(filepath=filepath) print(result["content"]) # Should print: Hello, World! ``` ## Common Tasks ### Create a document ``` User: Create a new Word document at ./report.docx with title "Monthly Report" Tool: create_docx(filepath="./report.docx", title="Monthly Report") ``` ### Write content ``` User: Write the following content to the document Tool: write_docx(filepath="./report.docx", content="Executive Summary\nKey Findings...") ``` ### Apply heading style ``` User: Make the first paragraph a heading Tool: apply_paragraph_style(filepath="./report.docx", paragraph_index=0, style_name="Heading 1") ``` ### Create a bulleted list ``` User: Make paragraphs 2-4 a bulleted list Tool: apply_bullet_list(filepath="./report.docx", paragraph_indices=[2,3,4]) ``` ### Insert an image ``` User: Insert image.png into the document Tool: insert_image(filepath="./report.docx", image_path="./image.png", width=3.0) ``` ## Troubleshooting ### "Command not found: python" Make sure you've activated the virtual environment: ```bash source venv/bin/activate ``` ### Import errors Reinstall dependencies: ```bash uv sync --upgrade ``` ### Permission denied on setup.sh Make it executable: ```bash chmod +x setup.sh run.sh ``` ### Can't find document Use absolute paths or paths relative to where you run the command from. ## Docker Setup (Alternative) ### Build and run with Docker ```bash docker-compose up -d ``` This will: - Build the Docker image - Create a `documents/` directory for files - Create a `logs/` directory for logs - Run the server in the background ### View logs ```bash docker-compose logs -f ``` ### Stop the server ```bash docker-compose down ``` ## Development ### Install development dependencies ```bash make install # or: uv sync ``` ### Run linting ```bash make lint # Check code style make format # Fix code style ``` ### Run type checking ```bash make type-check ``` ### Run all checks ```bash make test lint type-check ``` ## Next Steps 1. **Read the full documentation**: See [README.md](README.md) 2. **Explore available tools**: Check `src/docx_mcp/server.py` 3. **Review examples**: See the README.md for detailed examples 4. **Configure settings**: Edit environment variables for your use case ## Getting Help - Check `logs/` directory for detailed error messages - Review the docstrings in `src/docx_mcp/server.py` - Check the [README.md](README.md) for comprehensive documentation ## Environment Variables ```bash # Set project directory export DOCX_MCP_PROJECT_DIR=/path/to/documents # Set log level (DEBUG, INFO, WARNING, ERROR) export DOCX_MCP_LOG_LEVEL=INFO # Set maximum file size (bytes, default: 50MB) export DOCX_MCP_MAX_FILE_SIZE=52428800 ``` ## Performance Tips 1. Use absolute file paths for better performance 2. Avoid processing very large documents (> 50MB) 3. Run the server on an SSD for faster I/O 4. Use the Docker version for consistent performance --- You're all set! Start creating and manipulating Word documents with docx-mcp.