Fetch MCP Server

Multi-Architecture Docker Image for Distributed Deployment

NPM Package • GitHub Repository • Docker Hub

📋 Table of Contents

Overview
Quick Start
Configuration
MCP Client Setup
Available Tools
Advanced Usage
Troubleshooting
Resources & Support

Overview

Fetch MCP Server empowers AI assistants with powerful web content retrieval capabilities. Fetch any webpage and receive content in your preferred format—HTML, JSON, plain text, or Markdown. Seamlessly integrates with VS Code, Cursor, Windsurf, Claude Desktop, and any MCP-compatible client.

Key Features

✨ Multiple Format Support - HTML, JSON, plain text, and Markdown conversion
🔒 Secure & Configurable - Custom headers, SSL verification, redirect control
⚡ High Performance - Configurable timeouts, size limits, and redirect handling
🌐 CORS Ready - Built-in CORS support for browser-based clients
🚀 Multiple Protocols - HTTP, SSE, and WebSocket transport support
🎯 Zero Configuration - Works out of the box with sensible defaults
🔧 Highly Customizable - Fine-tune every aspect via environment variables
📊 Health Monitoring - Built-in health check endpoint

Supported Architectures

Architecture	Status	Notes
x86-64	✅ Stable	Intel/AMD processors
ARM64	✅ Stable	Raspberry Pi, Apple Silicon

Available Tags

Tag	Stability	Use Case
`stable`	⭐⭐⭐	Production (recommended)
`latest`	⭐⭐⭐	Latest stable features
`1.x.x`	⭐⭐⭐	Version pinning
`beta`	⚠️	Testing only

Quick Start

Prerequisites

Docker Engine 23.0+
Network access for fetching web content

Docker Compose (Recommended)

services:
  fetch-mcp:
    image: mekayelanik/fetch-mcp:stable
    container_name: fetch-mcp
    restart: unless-stopped
    ports:
      - "8060:8060"
    environment:
      - PORT=8060
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Dhaka
      - PROTOCOL=SHTTP
      - CORS=*
      - DEFAULT_LIMIT=0
      - FETCH_TIMEOUT=30000
      - MAX_REDIRECTS=5
      - FOLLOW_REDIRECTS=true
      - VERIFY_SSL=true

Deploy:

docker compose up -d
docker compose logs -f fetch-mcp

Docker CLI

docker run -d \
  --name=fetch-mcp \
  --restart=unless-stopped \
  -p 8060:8060 \
  -e PORT=8060 \
  -e PUID=1000 \
  -e PGID=1000 \
  -e PROTOCOL=SHTTP \
  -e CORS=* \
  mekayelanik/fetch-mcp:stable

Access Endpoints

Protocol	Endpoint	Use Case
HTTP	`http://host-ip:8060/mcp`	Recommended
SSE	`http://host-ip:8060/sse`	Real-time streaming
WebSocket	`ws://host-ip:8060/message`	Bidirectional
Health	`http://host-ip:8060/healthz`	Monitoring

⏱️ Server ready in 5-10 seconds after container start

Configuration

Environment Variables

Core Settings

Variable	Default	Description
`PORT`	`8060`	Server port (1-65535)
`PUID`	`1000`	User ID for file permissions
`PGID`	`1000`	Group ID for file permissions
`TZ`	`Asia/Dhaka`	Container timezone
`PROTOCOL`	`SHTTP`	Transport protocol
`CORS`	(none)	Cross-Origin configuration

Fetch Settings

Variable	Default	Description
`DEFAULT_LIMIT`	`0`	Max response size (bytes, 0=unlimited)
`FETCH_TIMEOUT`	`30000`	Request timeout (ms, 1000-300000)
`MAX_REDIRECTS`	`5`	Maximum redirect follow count (0-20)
`FOLLOW_REDIRECTS`	`true`	Enable automatic redirect following
`VERIFY_SSL`	`true`	Enable SSL certificate verification
`USER_AGENT`	(default)	Custom User-Agent header

Advanced Settings

Variable	Default	Description
`DEBUG_MODE`	`false`	Enable debug mode (`true`, `false`, `verbose`)

Protocol Configuration

# HTTP/Streamable HTTP (Recommended)
environment:
  - PROTOCOL=SHTTP

# Server-Sent Events
environment:
  - PROTOCOL=SSE

# WebSocket
environment:
  - PROTOCOL=WS

CORS Configuration

# Development - Allow all origins
environment:
  - CORS=*

# Production - Specific domains
environment:
  - CORS=https://example.com,https://app.example.com

# Mixed domains and IPs
environment:
  - CORS=https://example.com,192.168.1.100:3000,/.*\.myapp\.com$/

# Regex patterns
environment:
  - CORS=/^https:\/\/.*\.example\.com$/

⚠️ Security: Never use CORS=* in production environments

Size Limit Examples

# Unlimited (default)
environment:
  - DEFAULT_LIMIT=0

# 1 MB limit
environment:
  - DEFAULT_LIMIT=1048576

# 5 MB limit
environment:
  - DEFAULT_LIMIT=5242880

# 10 MB limit
environment:
  - DEFAULT_LIMIT=10485760

Timeout Examples

# Quick responses (10 seconds)
environment:
  - FETCH_TIMEOUT=10000

# Default (30 seconds)
environment:
  - FETCH_TIMEOUT=30000

# Long-running requests (2 minutes)
environment:
  - FETCH_TIMEOUT=120000

Custom User Agent

environment:
  - USER_AGENT=MyBot/1.0 (+https://example.com/bot)

MCP Client Setup

Transport Compatibility

Client	HTTP	SSE	WebSocket	Recommended
VS Code (Cline/Roo-Cline)	✅	✅	❌	HTTP
Claude Desktop	✅	✅	⚠️*	HTTP
Cursor	✅	✅	⚠️*	HTTP
Windsurf	✅	✅	⚠️*	HTTP

⚠️ *WebSocket support is experimental

VS Code (Cline/Roo-Cline)

Add to .vscode/settings.json:

{
  "mcp.servers": {
    "fetch": {
      "url": "http://host-ip:8060/mcp",
      "transport": "http",
      "autoApprove": [
        "fetch_html",
        "fetch_json",
        "fetch_txt",
        "fetch_markdown"
      ]
    }
  }
}

Claude Desktop

Config Locations:

Linux: ~/.config/Claude/claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fetch": {
      "transport": "http",
      "url": "http://localhost:8060/mcp"
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "fetch": {
      "transport": "http",
      "url": "http://host-ip:8060/mcp"
    }
  }
}

Windsurf (Codeium)

Add to .codeium/mcp_settings.json:

{
  "mcpServers": {
    "fetch": {
      "transport": "http",
      "url": "http://host-ip:8060/mcp"
    }
  }
}

Claude Code

Add to ~/.config/claude-code/mcp_config.json:

{
  "mcpServers": {
    "fetch": {
      "transport": "http",
      "url": "http://localhost:8060/mcp"
    }
  }
}

Or configure via CLI:

claude-code config mcp add fetch \
  --transport http \
  --url http://localhost:8060/mcp

GitHub Copilot CLI

Add to ~/.github-copilot/mcp.json:

{
  "mcpServers": {
    "fetch": {
      "transport": "http",
      "url": "http://host-ip:8060/mcp"
    }
  }
}

Or use environment variable:

export GITHUB_COPILOT_MCP_SERVERS='{"fetch":{"transport":"http","url":"http://localhost:8060/mcp"}}'

Available Tools

🌐 fetch_html

Fetch a website and return raw HTML content.

Parameters:

url (string, required): URL of the website to fetch
headers (object, optional): Custom headers for the request

Use Cases:

Scraping structured web data
Analyzing page structure
Testing web applications
Extracting specific HTML elements

Example Prompts:

"Fetch the HTML from https://example.com"
"Get the HTML of https://news.ycombinator.com with custom headers"
"Download the raw HTML from this page"

📦 fetch_json

Fetch and parse JSON data from a URL.

Parameters:

url (string, required): URL of the JSON resource
headers (object, optional): Custom headers for the request

Use Cases:

Consuming REST APIs
Reading configuration files
Processing structured data
API testing and debugging

Example Prompts:

"Fetch the JSON from https://api.example.com/data"
"Get JSON data from this API endpoint"
"Download and parse JSON from https://example.com/config.json"

📄 fetch_txt

Fetch a website and return clean plain text (HTML tags removed).

Parameters:

url (string, required): URL of the website to fetch
headers (object, optional): Custom headers for the request

Use Cases:

Reading articles and blog posts
Text analysis and processing
Content extraction without markup
Accessibility-focused content retrieval

Example Prompts:

"Get the text content from https://blog.example.com/post"
"Fetch plain text from this article"
"Extract text from https://example.com without HTML"

📝 fetch_markdown

Fetch a website and convert HTML to Markdown format.

Parameters:

url (string, required): URL of the website to fetch
headers (object, optional): Custom headers for the request

Use Cases:

Converting web content to Markdown
Creating documentation from web pages
Archiving web content in readable format
Content migration to Markdown-based systems

Example Prompts:

"Convert https://example.com to Markdown"
"Get this webpage in Markdown format"
"Fetch and convert this article to Markdown"

Advanced Usage

Custom Headers Example

{
  "url": "https://api.example.com/data",
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "User-Agent": "MyApp/1.0"
  }
}

Production Configuration

services:
  fetch-mcp:
    image: mekayelanik/fetch-mcp:stable
    container_name: fetch-mcp
    restart: unless-stopped
    ports:
      - "8060:8060"
    environment:
      # Core settings
      - PORT=8060
      - PUID=1000
      - PGID=1000
      - TZ=UTC
      - PROTOCOL=SHTTP
      
      # Security
      - CORS=https://app.example.com,https://admin.example.com
      - VERIFY_SSL=true
      
      # Performance
      - DEFAULT_LIMIT=5242880  # 5 MB limit
      - FETCH_TIMEOUT=30000    # 30 seconds
      - MAX_REDIRECTS=5
      - FOLLOW_REDIRECTS=true
      
      # Custom identification
      - USER_AGENT=MyCompany-Bot/1.0 (+https://example.com/bot)
    
    # Resource limits
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M
    
    # Health check
    healthcheck:
      test: ["CMD", "nc", "-z", "localhost", "8060"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

Reverse Proxy Setup

Nginx

server {
    listen 80;
    server_name fetch.example.com;
    
    location / {
        proxy_pass http://localhost:8060;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # Timeouts for long-running requests
        proxy_connect_timeout 300;
        proxy_send_timeout 300;
        proxy_read_timeout 300;
    }
}

Traefik

services:
  fetch-mcp:
    image: mekayelanik/fetch-mcp:stable
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.fetch-mcp.rule=Host(`fetch.example.com`)"
      - "traefik.http.routers.fetch-mcp.entrypoints=websecure"
      - "traefik.http.routers.fetch-mcp.tls.certresolver=myresolver"
      - "traefik.http.services.fetch-mcp.loadbalancer.server.port=8060"

Docker Network Setup

services:
  fetch-mcp:
    image: mekayelanik/fetch-mcp:stable
    container_name: fetch-mcp
    networks:
      - mcp-network
    environment:
      - PORT=8060
      - PROTOCOL=SHTTP
    
  other-service:
    image: other-service:latest
    networks:
      - mcp-network
    environment:
      - FETCH_MCP_URL=http://fetch-mcp:8060/mcp

networks:
  mcp-network:
    driver: bridge

Multiple Instances

services:
  fetch-mcp-primary:
    image: mekayelanik/fetch-mcp:stable
    container_name: fetch-mcp-primary
    ports:
      - "8060:8060"
    environment:
      - PORT=8060
      - FETCH_TIMEOUT=30000
  
  fetch-mcp-fast:
    image: mekayelanik/fetch-mcp:stable
    container_name: fetch-mcp-fast
    ports:
      - "8061:8060"
    environment:
      - PORT=8060
      - FETCH_TIMEOUT=10000
      - DEFAULT_LIMIT=1048576  # 1 MB for quick fetches
  
  fetch-mcp-large:
    image: mekayelanik/fetch-mcp:stable
    container_name: fetch-mcp-large
    ports:
      - "8062:8060"
    environment:
      - PORT=8060
      - FETCH_TIMEOUT=120000
      - DEFAULT_LIMIT=52428800  # 50 MB for large content

Troubleshooting

Pre-Flight Checklist

✅ Docker 23.0+
✅ Port 8060 available
✅ Network connectivity
✅ Latest stable image
✅ Correct environment variables

Common Issues

Container Won't Start

# Check logs
docker logs fetch-mcp

# Pull latest image
docker pull mekayelanik/fetch-mcp:stable

# Restart container
docker restart fetch-mcp

Connection Refused

# Verify container is running
docker ps | grep fetch-mcp

# Check port binding
docker port fetch-mcp

# Test health endpoint
curl http://localhost:8060/healthz

Timeout Errors

# Increase timeout for slow websites
environment:
  - FETCH_TIMEOUT=60000  # 60 seconds

# Adjust redirect limit
environment:
  - MAX_REDIRECTS=10

SSL Certificate Errors

# Disable SSL verification (not recommended for production)
environment:
  - VERIFY_SSL=false

# Or update CA certificates in container
docker exec fetch-mcp apk add --update ca-certificates

CORS Errors

# Development - allow all
environment:
  - CORS=*

# Production - specific origins
environment:
  - CORS=https://yourdomain.com,https://app.yourdomain.com

Permission Errors

# Check your user ID
id $USER

# Update PUID/PGID
environment:
  - PUID=1001  # Your actual UID
  - PGID=1001  # Your actual GID

Size Limit Exceeded

# Increase or remove size limit
environment:
  - DEFAULT_LIMIT=0  # Unlimited
  # or
  - DEFAULT_LIMIT=10485760  # 10 MB

Debug Mode

# Enable verbose debugging
environment:
  - DEBUG_MODE=verbose

# Then check logs
docker logs -f fetch-mcp

Health Check Testing

# Basic health check
curl http://localhost:8060/healthz

# Test MCP endpoint
curl http://localhost:8060/mcp

# Test with tool invocation
curl -X POST http://localhost:8060/mcp \
  -H "Content-Type: application/json" \
  -d '{"method":"tools/list"}'

Resources & Support

Documentation

MCP Resources

Getting Help

Docker Image Issues:

General Questions:

Check logs: docker logs fetch-mcp
Test health: curl http://localhost:8060/healthz
Review configuration in this README

Updating

# Docker Compose
docker compose pull
docker compose up -d

# Docker CLI
docker pull mekayelanik/fetch-mcp:stable
docker stop fetch-mcp
docker rm fetch-mcp
# Re-run your docker run command

Version Pinning

# Use specific version
services:
  fetch-mcp:
    image: mekayelanik/fetch-mcp:1.0.0

# Or use stable tag (recommended)
services:
  fetch-mcp:
    image: mekayelanik/fetch-mcp:stable

Performance Tips

Optimize for Speed

environment:
  - FETCH_TIMEOUT=10000      # Faster timeout
  - DEFAULT_LIMIT=1048576    # 1 MB limit
  - MAX_REDIRECTS=3          # Fewer redirects
  - FOLLOW_REDIRECTS=true

Optimize for Large Content

environment:
  - FETCH_TIMEOUT=120000     # 2 minutes
  - DEFAULT_LIMIT=0          # No limit
  - MAX_REDIRECTS=10

Resource Limits

deploy:
  resources:
    limits:
      cpus: '2.0'
      memory: 1G
    reservations:
      cpus: '1.0'
      memory: 512M

Security Best Practices

Never use CORS=* in production
Always use VERIFY_SSL=true except for development
Set appropriate size limits to prevent abuse
Use reverse proxy with rate limiting
Run as non-root (default PUID/PGID)
Monitor logs for suspicious activity
Keep Docker image updated
Use specific version tags for production

License

Docker Image: GPL License - See LICENSE for details.

Disclaimer: Unofficial Docker image for fetch-mcp. Users are responsible for compliance with terms of service of fetched websites and applicable laws.

Report docker image related Bug • Request Feature • Contribute

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
resources		resources
.gitignore		.gitignore
CREDITS.md		CREDITS.md
DockerfileModifier.sh		DockerfileModifier.sh
LICENSE		LICENSE
README.md		README.md

License

MekayelAnik/fetch-mcp-docker

Folders and files

Latest commit

History

Repository files navigation

Fetch MCP Server

Multi-Architecture Docker Image for Distributed Deployment

📋 Table of Contents

Overview

Key Features

Supported Architectures

Available Tags

Quick Start

Prerequisites

Docker Compose (Recommended)

Docker CLI

Access Endpoints

Configuration

Environment Variables

Core Settings

Fetch Settings

Advanced Settings

Protocol Configuration

CORS Configuration

Size Limit Examples

Timeout Examples

Custom User Agent

MCP Client Setup

Transport Compatibility

VS Code (Cline/Roo-Cline)

Claude Desktop

Cursor

Windsurf (Codeium)

Claude Code

GitHub Copilot CLI

Available Tools

🌐 fetch_html

📦 fetch_json

📄 fetch_txt

📝 fetch_markdown

Advanced Usage

Custom Headers Example

Production Configuration

Reverse Proxy Setup

Nginx

Traefik

Docker Network Setup

Multiple Instances

Troubleshooting

Pre-Flight Checklist

Common Issues

Health Check Testing

Resources & Support

Documentation

MCP Resources

Getting Help

Updating

Version Pinning

Performance Tips

Optimize for Speed

Optimize for Large Content

Resource Limits

Security Best Practices

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages