Super Fetch MCP Server

🚀 superFetch MCP Server

superFetch MCP Server is a Model Context Protocol (MCP) server. It can fetch web pages, extract readable content using Mozilla Readability, and return AI - friendly JSONL or Markdown, facilitating AI - related web content processing.

Quick Start | How to Choose a Tool | Tools | Resources | Configuration | Security | Development

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

🚀 Quick Start

You can add superFetch to your MCP client configuration without installation.

Claude Desktop

Add the following to your claude_desktop_config.json:

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

VS Code

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

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

With Custom Configuration

Configure SuperFetch behavior by adding environment variables to the env property:

{
  "servers": {
    "superFetch": {
      "command": "npx",
      "args": ["-y", "@j0hanz/superfetch@latest", "--stdio"],
      "env": {
        "CACHE_TTL": "7200",
        "LOG_LEVEL": "debug",
        "FETCH_TIMEOUT": "60000"
      }
    }
  }
}

See Configuration for all available options.

Cursor

1. Open Cursor Settings.
2. Go to Features > MCP Servers.
3. Click "+ Add new global MCP server".
4. Add the following 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"]

[mcp_servers.superfetch]
command = "npx"
args = ["-y", "@j0hanz/superfetch@latest", "--stdio"]
env = { CACHE_TTL = "7200", LOG_LEVEL = "debug", FETCH_TIMEOUT = "60000" }

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

✨ Features

📦 Installation

One-Click Install

Alternative Installation

Global Installation

npm install -g @j0hanz/superfetch

# Run in stdio mode
superfetch --stdio

# Run HTTP server (requires API_KEY)
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

💻 How to Choose a Tool

Use this guide to select the right tool for your web content extraction needs.

Decision Tree

Need web content for AI?
- Want structured JSONL blocks -> fetch-url (format: jsonl)
- Want clean Markdown -> fetch-markdown
- Want Markdown but also need contentBlocks count -> fetch-url (format: markdown)

Quick Reference Table

Common Use Cases

💻 Available Tools

Tool Response Notes

Both tools return:

• structuredContent for machine-readable fields
• content blocks that include:
  • a text block containing JSON of structuredContent
  • a resource block with a file:///... URI containing the full content (stdio-friendly)
  • a resource_link block when content exceeds MAX_INLINE_CONTENT_CHARS and cache is enabled

If content is too large and cache is disabled, the server truncates output and appends ...[truncated].

fetch-url

Fetches a webpage and converts it to AI-readable JSONL format with semantic content blocks. You can also request Markdown with format: "markdown".

Example structuredContent:

{
  "url": "https://example.com/article",
  "title": "Example Article",
  "contentBlocks": 42,
  "fetchedAt": "2025-12-11T10:30:00.000Z",
  "format": "jsonl",
  "contentSize": 12345,
  "cached": false,
  "content": "{\"type\":\"metadata\",\"title\":\"Example Article\",\"url\":\"https://example.com/article\"}\n{\"type\":\"heading\",\"level\":1,\"text\":\"Introduction\"}"
}

fetch-markdown

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

Example structuredContent:

{
  "url": "https://example.com/docs",
  "title": "Documentation",
  "fetchedAt": "2025-12-11T10:30:00.000Z",
  "markdown": "---\ntitle: Documentation\nsource: \"https://example.com/docs\"\n---\n\n# Getting Started\n\nWelcome...",
  "contentSize": 9876,
  "cached": false,
  "truncated": false,
  "file": {
    "downloadUrl": "/mcp/downloads/markdown/abc123def456",
    "fileName": "documentation.md",
    "expiresAt": "2025-12-11T11:30:00.000Z"
  }
}

file is included only in HTTP mode when content is cached and too large to inline.

Large Content Handling

• Inline limit: MAX_INLINE_CONTENT_CHARS (default 20000).
• If content exceeds the limit and cache is enabled, responses include resourceUri and a resource_link block.
• If cache is disabled, content is truncated with ...[truncated].
• Use maxContentLength per request to enforce a lower limit.

📚 Resources

Resource subscriptions notify clients when cache entries update.

📚 Download Endpoint (HTTP Mode)

When running in HTTP mode, cached content can be downloaded directly.

Endpoint

GET /mcp/downloads/:namespace/:hash

• namespace: markdown or url
• Auth required (Authorization: Bearer <API_KEY> or X-API-Key: <API_KEY>)

Response Headers

Example Usage

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

Error Responses

📚 Configuration

Configure SuperFetch behavior by adding environment variables to your MCP client configuration's env property.

Fetcher Settings

Cache Settings

Output Settings

Logging Settings

Extraction Settings

HTTP Server Settings

CORS Settings

Rate Limiting

Configuration Presets

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

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

{
  "servers": {
    "superFetch": {
      "command": "npx",
      "args": ["-y", "@j0hanz/superfetch@latest", "--stdio"],
      "env": {
        "CACHE_TTL": "7200",
        "CACHE_MAX_KEYS": "500",
        "LOG_LEVEL": "warn"
      }
    }
  }
}

{
  "servers": {
    "superFetch": {
      "command": "npx",
      "args": ["-y", "@j0hanz/superfetch@latest", "--stdio"],
      "env": {
        "USER_AGENT": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
      }
    }
  }
}

{
  "servers": {
    "superFetch": {
      "command": "npx",
      "args": ["-y", "@j0hanz/superfetch@latest", "--stdio"],
      "env": {
        "FETCH_TIMEOUT": "60000",
        "CACHE_ENABLED": "false",
        "LOG_LEVEL": "warn"
      }
    }
  }
}

📚 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 MAX_SESSIONS is reached, the server evicts the oldest session when possible, otherwise returns a 503.

📚 Content Block Types

JSONL output includes semantic content blocks:

🔧 Security

SSRF Protection

Blocked destinations include:

• Localhost and loopback addresses
• Private IP ranges (10.x.x.x, 172.16-31.x.x, 192.168.x.x)
• Cloud metadata endpoints (AWS, GCP, Azure)
• IPv6 link-local and unique local addresses
• Internal suffixes such as .local and .internal

URL Validation

• Only http and https URLs
• No embedded credentials in URLs
• Max URL length: 2048 characters

Header Sanitization

Blocked headers: host, authorization, cookie, x-forwarded-for, x-real-ip, proxy-authorization

Rate Limiting

Default: 100 requests/minute per IP (HTTP mode only). Configure with RATE_LIMIT_MAX and RATE_LIMIT_WINDOW_MS.

🔧 Development

Scripts

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

⚠️ Important Note

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.