MCP File Downloader 🚀
A Model Context Protocol (MCP) server that enables Claude Desktop to download files from the web, with automatic browser fallback for JavaScript-heavy sites.
🎯 Why This Exists
Claude Desktop can't natively download files. This MCP server bridges that gap, providing:
- Direct HTTP downloads with smart redirect handling
- Automatic browser-based fallback for complex sites
- Seamless integration with Claude Desktop
Perfect for downloading datasets, documents, and files from sites that use JavaScript for download links.
✨ Features
- Smart Download Strategy: Tries HTTP first, falls back to browser if needed
- 10-Level Redirect Support: Handles complex redirect chains
- JavaScript Rendering: Uses Playwright for sites requiring browser execution
- Flexible File Naming: Auto-names from URL or accepts custom names
- Cross-Platform: Works on Windows, macOS, and Linux
🚀 Quick Start
Prerequisites
- Node.js 18+
- Claude Desktop
Installation
- Clone the repository:
git clone https://github.com/yourusername/mcp-file-downloader.git
cd mcp-file-downloader
- Install dependencies:
npm install
- Add to Claude Desktop config:
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"file-downloader": {
"command": "node",
"args": ["C:\\path\\to\\mcp-file-downloader\\download-server.js"]
}
}
}
- Restart Claude Desktop
📖 Usage
In Claude Desktop, you can now download files:
"Download this file: https://example.com/data.csv"
"Get the PDF from https://example.com/report.pdf and save it as quarterly_report.pdf"
"Download https://site-with-javascript.com/dynamic-file.xlsx"
(automatically uses browser if HTTP fails)
Parameters
- url (required): The URL to download from
- filename (optional): Save as this filename. Can include full path
- use_browser (optional): Force browser download method
🔧 Advanced Usage
Force Browser Mode
For sites that always need JavaScript:
"Download https://complex-site.com/file.zip using browser mode"
Custom Save Location
"Download https://example.com/data.csv to ~/Documents/mydata.csv"
📂 Project Structure
mcp-file-downloader/
├── download-server.js # MCP server implementation
├── package.json # Dependencies
├── LICENSE # MIT license
├── README.md # This file
└── CLAUDE_HINTS.md # Advanced documentation
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
Development Setup
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
🐛 Troubleshooting
"Too many redirects" error
The site likely requires JavaScript. Use use_browser: true parameter.
Downloads failing
Check that Node.js has write permissions to your download directory.
Claude doesn't see the tool
- Verify the path in claude_desktop_config.json is correct
- Fully quit Claude Desktop (check system tray)
- Restart Claude Desktop
📝 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
- Built for the Model Context Protocol ecosystem
- Uses Playwright for browser automation
- Inspired by the need to download ETF holdings data in Claude Desktop
📧 Contact
For questions or support, please open an issue on GitHub.
Note: This is an independent project and not officially affiliated with Anthropic or Claude.