superFetch MCP Server

One-Click Install

A Model Context Protocol (MCP) server that fetches web pages, extracts readable content with Mozilla Readability, and returns AI-friendly Markdown.

Quick Start | Tool | Resources | Configuration | Security | Development

Published to MCP Registry - Search for io.github.j0hanz/superfetch

[!CAUTION] This server can access URLs on behalf of AI assistants. Built-in SSRF protection blocks private IP ranges and cloud metadata endpoints, but exercise caution when deploying in sensitive environments.

Features

Quick Start

Add superFetch to your MCP client configuration - no installation required.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "superFetch": {
      "command": "npx",
      "args": ["-y", "@j0hanz/superfetch@latest", "--stdio"]
    }
  }
}

VS Code

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "superFetch": {
      "command": "npx",
      "args": ["-y", "@j0hanz/superfetch@latest", "--stdio"]
    }
  }
}

With Custom Configuration

Add environment variables in your MCP client config under env. See Configuration or CONFIGURATION.md for all available options and presets.

Cursor

1. Open Cursor Settings
2. Go to Features > MCP Servers
3. Click "+ Add new global MCP server"
4. Add this configuration:

{
  "mcpServers": {
    "superFetch": {
      "command": "npx",
      "args": ["-y", "@j0hanz/superfetch@latest", "--stdio"]
    }
  }
}

Tip (Windows): If you encounter issues, try: cmd /c "npx -y @j0hanz/superfetch@latest --stdio"

[mcp_servers.superfetch]
command = "npx"
args = ["-y", "@j0hanz/superfetch@latest", "--stdio"]

code ~/Library/Application\ Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

code %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

{
  "mcpServers": {
    "superFetch": {
      "command": "npx",
      "args": ["-y", "@j0hanz/superfetch@latest", "--stdio"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

{
  "mcpServers": {
    "superFetch": {
      "command": "npx",
      "args": ["-y", "@j0hanz/superfetch@latest", "--stdio"]
    }
  }
}

# Open config file
open -e "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

# Or with VS Code
code "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

code %APPDATA%\Claude\claude_desktop_config.json

Installation (Alternative)

Global Installation

npm install -g @j0hanz/superfetch

# Run in stdio mode
superfetch --stdio

# Run HTTP server (requires auth token)
superfetch

From Source

git clone https://github.com/j0hanz/super-fetch-mcp-server.git
cd super-fetch-mcp-server
npm install
npm run build

Running the Server

node dist/index.js --stdio

API_KEY=supersecret npx -y @j0hanz/superfetch@latest
# Server runs at http://127.0.0.1:3000

$env:API_KEY = "supersecret"
npx -y @j0hanz/superfetch@latest

Available Tools

Tool Response Notes

The tool returns structuredContent with url, optional title, and markdown when inline content is available. On errors, error is included instead of content.

The response includes:

• a text block containing JSON of structuredContent
• a resource block embedding markdown when inline content is available (always in stdio mode)
• when content exceeds the inline limit and cache is enabled, a resource_link block pointing to superfetch://cache/... (inline markdown may be omitted)
• error responses set isError: true and return structuredContent with error and url

fetch-url

Fetches a webpage and converts it to clean Markdown format with optional frontmatter.

Example structuredContent:

{
  "url": "https://example.com/docs",
  "title": "Documentation",
  "markdown": "---\ntitle: Documentation\n---\n\n# Getting Started\n\nWelcome..."
}

Error response:

{
  "url": "https://example.com/broken",
  "error": "Failed to fetch: 404 Not Found"
}

Large Content Handling

• Inline markdown is capped at 20,000 characters (maxInlineContentChars).
• Stdio mode: full markdown is embedded as a resource block.
• HTTP mode: if content exceeds the inline limit and cache is enabled, the response includes a resource_link to superfetch://cache/... (no embedded markdown). If cache is disabled, the inline markdown is truncated with ...[truncated].
• Upstream fetch size is capped at 10 MB of HTML; larger responses fail.

Resources

Resource listings enumerate cached entries, and subscriptions notify clients when cache entries update.

Download Endpoint (HTTP Mode)

When running in HTTP mode, cached content can be downloaded directly. Downloads are available only when cache is enabled.

Endpoint

GET /mcp/downloads/:namespace/:hash

• namespace: markdown
• Auth required (Authorization: Bearer <token>; in static token mode, X-API-Key is accepted)

Response Headers

Example Usage

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3000/mcp/downloads/markdown/abc123.def456 \
  -o article.md

Error Responses

Configuration

Set environment variables in your MCP client env or in the shell before starting the server.

Core Server Settings

Auth (HTTP Mode)

Static mode requires at least one token (ACCESS_TOKENS or API_KEY).

OAuth (HTTP Mode)

Required when AUTH_MODE=oauth (or auto-selected by presence of OAuth URLs):

Optional:

Fixed Limits (Not Configurable via env)

• Fetch timeout: 15 seconds
• Max redirects: 5
• Max HTML response size: 10 MB
• Inline markdown limit: 20,000 characters
• Cache max entries: 100
• Session TTL: 30 minutes
• Session init timeout: 10 seconds
• Max sessions: 200
• Rate limit: 100 req/min per IP (60s window)

See CONFIGURATION.md for preset examples and quick-start snippets.

HTTP Mode Details

HTTP mode uses the MCP Streamable HTTP transport. The workflow is:

1. POST /mcp with an initialize request and no mcp-session-id header.
2. The server returns mcp-session-id in the response headers.
3. Use that header for subsequent POST /mcp, GET /mcp, and DELETE /mcp requests.

If the mcp-protocol-version header is missing, the server defaults it to 2025-03-26. Supported versions are 2025-03-26 and 2025-11-25.

GET /mcp and DELETE /mcp require mcp-session-id. POST /mcp without an initialize request will return 400.

Additional HTTP transport notes:

• GET /mcp requires Accept: text/event-stream (otherwise 406).
• JSON-RPC batch requests are not supported (400).

If the server reaches its session cap (200), it evicts the oldest session when possible; otherwise it returns a 503.

Host and Origin headers are always validated. Allowed values include loopback hosts, the configured HOST (if not a wildcard), and any entries in ALLOWED_HOSTS. When binding to 0.0.0.0 or ::, set ALLOWED_HOSTS to the hostnames clients will send.

Security

SSRF Protection

Blocked destinations include:

• Loopback and unspecified addresses (127.0.0.0/8, ::1, 0.0.0.0, ::)
• Private/ULA ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7)
• Link-local and shared address space (169.254.0.0/16, 100.64.0.0/10, fe80::/10)
• Multicast/reserved ranges (224.0.0.0/4, 240.0.0.0/4, ff00::/8)
• IPv6 transition ranges (64:ff9b::/96, 64:ff9b:1::/48, 2001::/32, 2002::/16)
• Cloud metadata endpoints (AWS/GCP/Azure/Alibaba) like 169.254.169.254, metadata.google.internal, metadata.azure.com, 100.100.100.200, instance-data
• Internal suffixes such as .local and .internal

DNS resolution is performed and blocked if any resolved IP matches a blocked range.

URL Validation

• Only http and https URLs
• No embedded credentials in URLs
• Max URL length: 2048 characters
• Hostnames ending in .local or .internal are rejected

Host/Origin Validation (HTTP Mode)

• Host header must match loopback, configured HOST (if not a wildcard), or ALLOWED_HOSTS
• Origin header (when present) is validated against the same allow-list

Rate Limiting

Rate limiting applies to /mcp and /mcp/downloads (100 req/min per IP, 60s window). OPTIONS requests are not rate-limited.

Development

Scripts

Note: Tests run via node --test with --experimental-transform-types to execute .ts test files. Node will emit an experimental warning.

Tech Stack

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Ensure linting passes: npm run lint
4. Run tests: npm test
5. Commit changes: git commit -m 'Add amazing feature'
6. Push: git push origin feature/amazing-feature
7. Open a Pull Request

For examples of other MCP servers, see: github.com/modelcontextprotocol/servers