Content
# paimon-mcp-fetch
**Give your AI assistant the ability to read any webpage.**
A lightweight MCP server that fetches URLs and returns clean, readable markdown. Built with Go — starts in 5ms, uses ~10MB RAM, zero runtime dependencies.
[](https://github.com/paimonchan/paimon-mcp-fetch/releases)
[](https://go.dev/dl/)
[](LICENSE)
---
## What It Does
You give it a URL → it returns clean markdown.
**Good for:**
- Reading articles, blog posts, documentation
- Extracting data from news sites, forums, schedules
- Summarizing web content for your AI assistant
- Getting structured output (headings, lists, tables, code blocks preserved)
**Not good for:**
- Scraping login-protected pages
- Bypassing paywalls
- Replacing a full browser automation tool
---
## Quick Start
### 1. Install
Pick one method:
```bash
# Go (recommended)
go install github.com/paimonchan/paimon-mcp-fetch/cmd/paimon-mcp-fetch@latest
# Homebrew (macOS/Linux)
brew tap paimonchan/tap
brew install paimon-mcp-fetch
# Scoop (Windows)
scoop bucket add paimonchan https://github.com/paimonchan/scoop-bucket
scoop install paimon-mcp-fetch
# Winget (Windows)
winget install paimonchan.paimon-mcp-fetch
# Docker
docker run -i --rm ghcr.io/paimonchan/paimon-mcp-fetch:latest
```
### 2. Configure Your AI Assistant
Add this to your MCP client config:
```json
{
"mcp": {
"paimon-mcp-fetch": {
"type": "local",
"command": ["paimon-mcp-fetch"],
"enabled": true
}
}
}
```
### 3. Done
Your AI can now read any URL you give it.
---
## Why This Over Other Fetch Tools?
| | paimon-mcp-fetch | Basic text fetch |
|--|------------------|------------------|
| **Output** | Structured markdown | Plain text |
| **Article extraction** | Readability algorithm (strips ads, nav, sidebars) | Raw HTML body |
| **Images** | Optional extraction + processing | None |
| **JS rendering** | Optional (headless Chrome) | Static only |
| **Caching** | Built-in LRU cache | None |
| **Rate limiting** | Per-domain, configurable | None |
| **SSRF protection** | 7-layer defense | None |
| **Startup time** | ~5ms | Varies |
| **Memory** | ~10MB | Varies |
---
## Configuration
Everything is controlled via environment variables. You probably don't need to change anything — defaults work well for most use cases.
| Variable | Default | What it does |
|----------|---------|--------------|
| `PAIMON_MCP_FETCH_TIMEOUT_MS` | `12000` | Request timeout (ms) |
| `PAIMON_MCP_FETCH_MAX_HTML_BYTES` | `10485760` | Max page size (10MB) |
| `PAIMON_MCP_FETCH_CACHE_TTL_SECS` | `300` | Cache lifetime (5 min) |
| `PAIMON_MCP_FETCH_RATE_LIMIT_PER_SECOND` | `5.0` | Requests/sec per domain |
| `PAIMON_MCP_FETCH_RATE_LIMIT_BURST` | `10` | Max burst size |
| `PAIMON_MCP_FETCH_RETRY_MAX_ATTEMPTS` | `3` | Retry on transient errors |
| `PAIMON_MCP_FETCH_JS_RENDER_ENABLED` | `false` | Enable headless Chrome |
---
## Optional Features
### Image Processing
Extract and process images from webpages:
```bash
go build -tags image -o paimon-mcp-fetch ./cmd/paimon-mcp-fetch/
```
### JS Rendering
For JavaScript-heavy sites (SPAs, dynamic content):
```bash
go build -tags jsrender -o paimon-mcp-fetch ./cmd/paimon-mcp-fetch/
PAIMON_MCP_FETCH_JS_RENDER_ENABLED=true ./paimon-mcp-fetch
```
**Note:** Requires Chrome or Chromium installed. Slower (~3-5s/page) but handles sites that static fetch can't.
---
## Supported AI Assistants
Works with any MCP-compatible client. Add the configuration below to your client's config file.
### OpenCode
**Config file:** `~/.config/opencode/opencode.json`
```json
{
"mcp": {
"paimon-mcp-fetch": {
"type": "local",
"command": ["paimon-mcp-fetch"],
"enabled": true
}
}
}
```
### Claude Desktop
**Config file:** `claude_desktop_config.json`
```json
{
"mcpServers": {
"paimon-mcp-fetch": {
"command": "paimon-mcp-fetch"
}
}
}
```
### Cursor
**Config file:** `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global)
```json
{
"mcpServers": {
"paimon-mcp-fetch": {
"command": "paimon-mcp-fetch",
"env": {}
}
}
}
```
### VS Code (GitHub Copilot)
**Config file:** `.vscode/mcp.json` (workspace) or user settings
```json
{
"servers": {
"paimon-mcp-fetch": {
"type": "stdio",
"command": "paimon-mcp-fetch"
}
}
}
```
### Cline
**Config file:** `.cline/mcp.json`
```json
{
"mcpServers": {
"paimon-mcp-fetch": {
"command": "paimon-mcp-fetch"
}
}
}
```
### Windsurf
**Config file:** `.windsurf/mcp.json`
```json
{
"mcpServers": {
"paimon-mcp-fetch": {
"command": "paimon-mcp-fetch"
}
}
}
```
### With Custom Configuration
All clients support environment variables. Example with custom timeout and cache:
```json
{
"mcpServers": {
"paimon-mcp-fetch": {
"command": "paimon-mcp-fetch",
"env": {
"PAIMON_MCP_FETCH_TIMEOUT_MS": "30000",
"PAIMON_MCP_FETCH_CACHE_TTL_SECS": "600"
}
}
}
}
```
---
## Security
Built with security in mind from day one:
- **SSRF Protection** — 7-layer defense against server-side request forgery
- **Private IP blocking** — Can't access localhost or internal networks
- **Redirect validation** — Every redirect hop re-checked for safety
- **Size limits** — Stream-based reading, no memory bombs
- **Timeouts** — All requests have deadlines
- **No secrets in logs** — API keys and tokens never logged
### Windows Antivirus
Some antivirus may flag unsigned Go binaries as a false positive. This is a known industry issue. Solutions:
1. Use `go install` — antivirus sees the signed Go compiler
2. Use Docker — no local binary
3. Build from source — verify the code yourself
---
## Architecture
Built with Clean Architecture principles:
```
MCP Server → UseCase → Domain (entities, ports)
↑
Adapters implement interfaces
```
- **Domain** — Business rules, zero external dependencies
- **UseCase** — Orchestration logic
- **Adapters** — HTTP client, content extractor, cache, rate limiter, image processor, JS renderer
Full details in the [project plan](https://github.com/paimonchan/mcp-plan).
---
## License
MIT — do whatever you want with it.
---
> Built with Go. Zero runtime dependencies. Single binary. ~10MB RAM. Starts in 5ms.
