# Web Clipper MCP Server

MCP server for clipping web pages to Markdown with local images.

## Installation

### Using uvx (Recommended)

```bash
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Add to Claude Desktop config (~/.config/claude/claude_desktop_config.json)
```

```json
{
  "mcpServers": {
    "web-clipper": {
      "command": "uvx",
      "args": ["--from", "/Users/like/research/web-clipper-mcp", "web-clipper-mcp"]
    }
  }
}
```

### Using pip

```bash
cd /Users/like/research/web-clipper-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

```json
{
  "mcpServers": {
    "web-clipper": {
      "command": "/Users/like/research/web-clipper-mcp/.venv/bin/python",
      "args": ["-m", "web_clipper_mcp.server"]
    }
  }
}
```

## Tools

### get_page_structure

Analyze a web page's structure and return a summary with CSS selector suggestions.

**Parameters:**
- `url` (required): The URL to analyze

**Example:**
```
Analyze https://example.com/article
```

### clip_url

Extract content from a URL and convert to Markdown.

**Parameters:**
- `url` (required): The URL to clip
- `selector` (optional): CSS selector to extract specific content
- `save_to` (optional): File path to save the Markdown (default: ~/Downloads/web-clipper/{YYYY-MM-DD}-{timestamp}/{title}.md)
- `download_images` (optional): Whether to download images locally (default: true)
- `force_image_attr` (optional): Force using specific attribute for images (e.g., "data-src", "src", "file")

**Example:**
```
Save https://example.com/article to ~/notes/article.md
```

### clip_html

Convert raw HTML to Markdown.

**Parameters:**
- `html` (required): Raw HTML content to convert
- `base_url` (optional): Base URL for resolving relative image URLs
- `save_to` (optional): File path to save the Markdown
- `download_images` (optional): Whether to download images locally (default: true)

**Example:**
```
Convert this HTML to Markdown: <div>...</div>
```

## Usage

1. Install the MCP server
2. Add to Claude Desktop config
3. Restart Claude Desktop
4. Use natural language to clip web pages:

```
帮我保存 https://example.com/article
```

```
这篇文章的结构是什么？ https://example.com/article
```

```
把这段 HTML 转成 Markdown: <div>...</div>
```

## Prompt

### clip-webpage

Recommended workflow for clipping web pages. Guides the LLM through: analyzing page structure, identifying content area, and calling clip_url with appropriate parameters.

**Arguments:**
- `url` (required): The URL to clip
- `content_selector` (optional): CSS selector for content area (e.g., `article`, `div.post`)

## Features

- Auto-extract main content using Readability
- CSS selector support for manual content selection
- Local image download and path replacement
- Markdown output with proper formatting
- Batch image lazy-loading pattern detection
- Force image attribute selection for ambiguous cases
- Automatic save with timestamp folder to prevent overwrites