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