{
  "markdown": "# HTML to Markdown MCP Server\n\nMCP (Model Context Protocol) server for converting HTML webpages to clean Markdown format. Reduces HTML size by ~90-95% while preserving tables, images, and important content - perfect for AI context.\n\n## Features\n\n- Converts HTML from URLs to clean Markdown\n- Preserves tables, images, and links\n- Removes unnecessary elements (scripts, styles, navigation, footers, headers)\n- Significant size reduction (typically 90-95% compression)\n- Configurable options for images, tables, and links\n- Built with `trafilatura` and `BeautifulSoup4` for robust extraction\n- **Stream processing** for efficient handling of large pages\n- **Size limits** to prevent downloading excessively large content (1MB-50MB)\n- **Optional caching** to speed up repeated conversions of the same URLs\n- **🌐 Browser mode with Playwright** - Handles JavaScript-heavy sites and authenticated pages\n  - Execute JavaScript (perfect for SPAs: React, Vue, Angular)\n  - Use your browser profile with cookies (access authenticated pages!)\n  - Support for Chrome, Firefox, WebKit\n  - Configurable wait strategies for dynamic content\n\n## Installation\n\n### Prerequisites\n\n- Python 3.10 or higher\n- `uv` package manager (recommended) or `pip`\n\n### Install with uv (recommended)\n\n```bash\n# Clone the repository\ngit clone <your-repo-url>\ncd html2md\n\n# Install dependencies\nuv pip install -e .\n\n# Install Playwright browsers (required for browser mode)\nplaywright install chromium\n```\n\n### Install with pip\n\n```bash\n# Clone the repository\ngit clone <your-repo-url>\ncd html2md\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install dependencies\npip install -e .\n\n# Install Playwright browsers (required for browser mode)\nplaywright install chromium\n```\n\n### Docker Installation (Recommended for Production)\n\nThe easiest way to use html2md is with Docker:\n\n```bash\n# Build the image\ndocker build -t html2md .\n\n# Or use pre-built image (when published)\ndocker pull your-registry/html2md:latest\n```\n\nFor Claude Desktop, configure with Docker:\n\n```json\n{\n  \"mcpServers\": {\n    \"html2md\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"-i\",\n        \"--rm\",\n        \"html2md\"\n      ]\n    }\n  }\n}\n```\n\n**Docker Image Features:**\n- Pre-installed Playwright with Chromium\n- Optimized for minimal size (~1GB)\n- Non-root user for security\n- Ready to use - no additional setup required\n\n## Configuration\n\nAdd the server to your Claude Desktop configuration file:\n\n### macOS\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"html2md\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"/absolute/path/to/html2md\",\n        \"run\",\n        \"html2md\"\n      ]\n    }\n  }\n}\n```\n\n### Windows\n\nEdit `%APPDATA%/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"html2md\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"C:\\\\absolute\\\\path\\\\to\\\\html2md\",\n        \"run\",\n        \"html2md\"\n      ]\n    }\n  }\n}\n```\n\n### Linux\n\nEdit `~/.config/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"html2md\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"/absolute/path/to/html2md\",\n        \"run\",\n        \"html2md\"\n      ]\n    }\n  }\n}\n```\n\n## Usage\n\nOnce configured, the MCP server will be available in Claude Desktop. You can use the `html_to_markdown` tool:\n\n### Example 1: Basic conversion\n\n```\nConvert this webpage to markdown: https://example.com/article\n```\n\n### Example 2: With options\n\n```\nUse the html_to_markdown tool with:\n- url: https://example.com/docs\n- include_images: false\n- include_tables: true\n```\n\n### Example 3: Browser mode for JavaScript-heavy sites\n\n```\nUse the html_to_markdown tool with:\n- url: https://spa-application.com\n- fetch_method: playwright\n- wait_for: networkidle\n```\n\n### Example 4: Access authenticated pages\n\n```\nUse the html_to_markdown tool with:\n- url: https://private-site.com/dashboard\n- fetch_method: playwright\n- use_user_profile: true\n- browser_type: chromium\n```\n\n**Note:** For `use_user_profile=true`, make sure Chrome is closed before running.\n\n### Tool Parameters\n\n**Basic Parameters:**\n- `url` (required): URL of the webpage to convert\n- `include_images` (optional, default: true): Include images in Markdown\n- `include_tables` (optional, default: true): Include tables in Markdown\n- `include_links` (optional, default: true): Include links in Markdown\n- `timeout` (optional, default: 30): Request timeout in seconds (5-120)\n\n**Performance Parameters:**\n- `max_size` (optional, default: 10MB): Maximum size of content to download in bytes (1MB-50MB)\n- `use_cache` (optional, default: false): Enable caching for faster repeated conversions\n- `cache_ttl` (optional, default: 3600): Cache time-to-live in seconds (60-86400)\n\n**Browser Mode Parameters:**\n- `fetch_method` (optional, default: \"fetch\"): Fetch method - \"fetch\" (fast) or \"playwright\" (handles JS, auth)\n- `browser_type` (optional, default: \"chromium\"): Browser to use - \"chromium\", \"firefox\", or \"webkit\"\n- `headless` (optional, default: true): Run browser in headless mode\n- `wait_for` (optional, default: \"networkidle\"): Wait strategy - \"load\", \"domcontentloaded\", or \"networkidle\"\n- `use_user_profile` (optional, default: false): Use your browser profile with cookies (requires Chrome closed)\n\n## Development\n\n### Install development dependencies\n\n```bash\nuv pip install -e \".[dev]\"\n```\n\n### Run tests\n\n```bash\npytest\n```\n\n### Code formatting\n\n```bash\n# Format with black\nblack src/ tests/\n\n# Lint with ruff\nruff check src/ tests/\n```\n\n### Type checking\n\n```bash\nmypy src/\n```\n\n## Architecture\n\nThe project consists of three main modules:\n\n### `converter.py`\nCore HTML to Markdown conversion functionality:\n- `fetch_html()`: Downloads HTML from URL\n- `clean_html()`: Removes unnecessary elements with BeautifulSoup\n- `convert_to_markdown()`: Converts cleaned HTML to Markdown with trafilatura\n- `html_to_markdown()`: Main workflow combining all steps\n\n### `server.py`\nMCP server implementation:\n- Registers the `html_to_markdown` tool\n- Handles tool calls and error responses\n- Runs async MCP server with stdio transport\n\n### `utils.py`\nUtility functions:\n- Hash calculation for caching\n- Text formatting and truncation\n- Domain extraction\n- Filename sanitization\n\n### `cache.py`\nIn-memory caching system:\n- `SimpleCache` class with TTL support\n- Global cache instance management\n- Automatic expiration of old entries\n- Hash-based cache keys for URL + parameters\n\n### `browser.py`\nPlaywright browser automation:\n- `fetch_html_playwright()` - Async browser-based HTML fetching\n- Support for Chromium, Firefox, WebKit\n- User profile integration for authenticated access\n- Configurable wait strategies for dynamic content\n\n## Troubleshooting\n\n### Server not appearing in Claude Desktop\n\n1. Check that the path in `claude_desktop_config.json` is absolute and correct\n2. Restart Claude Desktop completely\n3. Check Claude Desktop logs for errors\n\n### Installation issues\n\n```bash\n# Verify Python version\npython --version  # Should be 3.10+\n\n# Try reinstalling dependencies\nuv pip install --force-reinstall -e .\n```\n\n### Conversion errors\n\n- **Timeout errors**: Increase the `timeout` parameter\n- **Empty content**: Some websites may block automated requests or use JavaScript rendering\n  - **Solution**: Use `fetch_method: playwright` to execute JavaScript\n- **Parse errors**: The webpage structure may be unusual or malformed\n- **Content too large**: Increase the `max_size` parameter (up to 50MB) or the page exceeds limits\n- **Cache issues**: Disable caching with `use_cache: false` if you need fresh content\n\n### Browser mode issues\n\n- **Playwright not installed**: Run `playwright install chromium`\n- **Browser launch fails**: Check that you have sufficient permissions and disk space\n- **User profile error**: Make sure Chrome is completely closed before using `use_user_profile: true`\n- **Page doesn't load fully**: Try different `wait_for` strategies:\n  - `\"load\"` - fastest, waits for page load event\n  - `\"domcontentloaded\"` - waits for DOM to be ready\n  - `\"networkidle\"` - slowest but most reliable, waits for network to be idle\n- **Authentication not working**: Ensure you're using `browser_type: chromium` and `use_user_profile: true`\n\n## Performance\n\nTypical conversion results:\n- Original HTML: ~500KB - 2MB\n- Markdown output: ~25KB - 100KB\n- Compression: 90-95%\n- Processing time: 2-10 seconds (depending on page size and network)\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues or pull requests.\n\n## Credits\n\nBuilt with:\n- [MCP SDK](https://github.com/anthropics/mcp) - Model Context Protocol\n- [trafilatura](https://github.com/adbar/trafilatura) - Web content extraction\n- [BeautifulSoup4](https://www.crummy.com/software/BeautifulSoup/) - HTML parsing\n",
  "bytes": 8943,
  "sha": "55859146dc21a6702edd4539f557f92f437e658bfc10ff592b65c89854a688dc",
  "repo_slug": "sunshad0w/html2md-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sunshad0w_html2md_497dda84/readme"
}