Super Fetch MCP Server

🚀 superFetch MCP Server

superFetch MCP Server是一個模型上下文協議（MCP）服務器，它可以抓取網頁，使用Mozilla Readability提取可讀內容，並返回對AI友好的JSONL或Markdown格式數據。

快速開始 | 如何選擇工具 | 可用工具 | 資源 | 配置 | 安全 | 開發

已發佈到 MCP Registry - 搜索 io.github.j0hanz/superfetch

⚠️ 重要提示

此服務器可以代表AI助手訪問URL。內置的SSRF保護會阻止私有IP範圍和雲元數據端點，但在敏感環境中部署時仍需謹慎。

✨ 主要特性

🚀 快速開始

將superFetch添加到您的MCP客戶端配置中，無需安裝。

Claude Desktop

在claude_desktop_config.json中添加以下內容：

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

VS Code

在工作區的.vscode/mcp.json中添加以下內容：

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

自定義配置

通過在env屬性中添加環境變量來配置SuperFetch的行為：

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

更多可用選項請參考配置部分。

Cursor

1. 打開Cursor設置
2. 轉到 功能 > MCP服務器
3. 點擊 "+ 添加新的全局MCP服務器"
4. 添加以下配置：

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

💡 使用建議

（Windows）：如果遇到問題，請嘗試使用：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 -e "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

# 或者使用VS Code打開
code "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

code %APPDATA%\Claude\claude_desktop_config.json

📦 安裝指南

全局安裝

npm install -g @j0hanz/superfetch

# 以stdio模式運行
superfetch --stdio

# 運行HTTP服務器（需要API_KEY）
superfetch

從源代碼安裝

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

運行服務器

node dist/index.js --stdio

API_KEY=supersecret npx -y @j0hanz/superfetch@latest
# 服務器運行在 http://127.0.0.1:3000

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

💻 使用示例

基礎用法

以下是使用fetch-url工具的示例：

{
  "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工具幷包含文件信息的示例：

{
  "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"
  }
}

可用工具

工具響應說明

兩個工具都會返回：

• structuredContent，包含機器可讀的字段
• content塊，其中包括：
  • 一個text塊，包含structuredContent的JSON數據
  • 一個resource塊，包含一個file:///... URI，指向完整內容（適合stdio模式）
  • 當內容超過MAX_INLINE_CONTENT_CHARS且緩存啟用時，會有一個resource_link塊

如果內容過大且緩存禁用，服務器會截斷輸出並追加...[truncated]。

fetch-url

抓取網頁並將其轉換為包含語義內容塊的AI可讀JSONL格式。您也可以通過format: "markdown"請求Markdown格式。

fetch-markdown

抓取網頁並將其轉換為簡潔的Markdown格式，可選擇包含前置元數據。

大內容處理

• 內聯限制：MAX_INLINE_CONTENT_CHARS（默認20000）。
• 如果內容超過限制且緩存啟用，響應會包含resourceUri和resource_link塊。
• 如果緩存禁用，內容會被截斷並追加...[truncated]。
• 可以通過每個請求的maxContentLength參數設置更低的限制。

資源

資源訂閱會在緩存條目更新時通知客戶端。

下載端點（HTTP模式）

在HTTP模式下運行時，可以直接下載緩存的內容。

端點

GET /mcp/downloads/:namespace/:hash

• namespace：markdown 或 url
• 需要認證（Authorization: Bearer <API_KEY> 或 X-API-Key: <API_KEY>）

響應頭

示例用法

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

錯誤響應

📚 詳細文檔

配置

通過在MCP客戶端配置的env屬性中添加環境變量來配置SuperFetch的行為。

配置預設

{
  "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模式詳情

HTTP模式使用MCP可流式HTTP傳輸。工作流程如下：

1. 發送POST /mcp請求，包含initialize請求，且不包含mcp-session-id頭部。
2. 服務器在響應頭中返回mcp-session-id。
3. 在後續的POST /mcp、GET /mcp和DELETE /mcp請求中使用該頭部。

如果達到MAX_SESSIONS，服務器會盡可能淘汰最舊的會話，否則返回503。

內容塊類型

JSONL輸出包含語義內容塊：

🔧 技術細節

安全

SSRF保護

阻止的目標包括：

• 本地主機和迴環地址
• 私有IP範圍（10.x.x.x、172.16 - 31.x.x、192.168.x.x）
• 雲元數據端點（AWS、GCP、Azure）
• IPv6鏈路本地和唯一本地地址
• 內部後綴，如.local和.internal

URL驗證

• 僅允許http和https URL
• URL中不允許嵌入憑據
• 最大URL長度：2048字符

頭部清理

阻止的頭部：host、authorization、cookie、x-forwarded-for、x-real-ip、proxy-authorization

速率限制

默認：每個IP 100請求/分鐘（僅HTTP模式）。可通過RATE_LIMIT_MAX和RATE_LIMIT_WINDOW_MS進行配置。

開發

腳本

技術棧

📄 許可證

文檔中未提及許可證相關信息。

貢獻

1. 分叉倉庫
2. 創建功能分支：git checkout -b feature/amazing-feature
3. 確保代碼通過檢查：npm run lint
4. 運行測試：npm test
5. 提交更改：git commit -m 'Add amazing feature'
6. 推送：git push origin feature/amazing-feature
7. 打開拉取請求

其他MCP服務器示例，請參考：github.com/modelcontextprotocol/servers