mcp-npx-fetch

你正在开发一个AI应用，需要从网上获取一些数据。可能是抓取一个HTML页面，也可能是调用一个返回JSON的API，或者只是提取网页中的纯文本。通常你需要根据不同的内容类型写不同的处理逻辑，而且还要考虑格式转换、错误处理等细节。

现在有一个轻量级的工具可以让这个过程变得统一而简单。mcp-npx-fetch是一个MCP服务器，它专注于做一件事：从URL获取内容，并以你需要的格式返回。无论是原始的HTML、解析后的JSON、干净的纯文本，还是结构化的Markdown，它都能一键完成。配置好之后，你只需要告诉AI“把这个网页转成Markdown”，它就会自动处理所有转换细节。

项目基本信息

一、项目介绍

mcp-npx-fetch是一个轻量级的MCP服务器，它的功能很纯粹：获取网络内容并转换成多种格式。这个项目基于TypeScript开发，使用了JSDOM进行HTML解析，Turndown库将HTML转换为Markdown，并通过Model Context Protocol SDK提供标准的MCP接口。

这个服务器提供了四个核心工具，对应不同的输出格式：

fetch_html（获取HTML）

直接返回服务器响应原始HTML内容。适合你需要分析页面结构、查找特定元素、或者自己进行深度解析的场景。

fetch_json（获取JSON）

发送HTTP请求并自动解析JSON响应。如果响应不是有效的JSON，会返回错误。这是调用RESTful API的理想工具。

fetch_txt（获取纯文本）

获取网页内容后，自动去除所有HTML标签、脚本和样式，只留下干净的文本内容。适合需要快速阅读文章主体，而不关心格式的情况。

fetch_markdown（获取Markdown）

这是最常用的工具。它将HTML内容智能地转换成格式良好的Markdown。标题、列表、代码块、链接、图片等元素都会被正确地转换。

每个工具都支持自定义请求头（headers）。这意味着你可以添加认证信息（如Bearer Token）、设置用户代理、或者模拟特定的客户端。

项目的技术栈很现代：TypeScript提供类型安全，Zod做运行时参数验证，JSDOM负责HTML解析，Turndown处理Markdown转换。整个设计专注于可靠性和易用性。

二、核心优势

极致的简单性

这个项目只做一件事，但做得很好。它没有复杂的工具选择、没有过滤选项、没有爬虫逻辑。唯一的参数就是URL和可选的请求头。这种简单性意味着你可以快速上手，而且出错的可能性很小。

多格式一键转换

同一个URL，你可以获得四种不同格式的输出。不需要自己写HTML解析器，不需要处理正则表达式清理文本，也不需要找库来转换Markdown。所有繁重的工作都封装在工具内部。

自定义请求头支持

这是一个很重要的特性。很多有用的API需要认证（比如Bearer Token），或者某些网站需要特定的User-Agent才能访问。通过自定义请求头，你可以轻松应对这些场景。

轻量级且快速

项目的代码量很小，依赖也比较精简。启动速度快，每次请求的延迟低。对于需要频繁获取网络内容的AI应用来说，这很重要。

无外部服务依赖

所有的转换都在本地完成，不依赖任何外部API。这意味着没有速率限制（除了目标网站），没有额外的费用，也没有隐私顾虑。

MCP标准集成

作为标准的MCP服务器，它可以与任何支持MCP协议的客户端无缝集成。Claude Desktop、Cursor、Windsurf等都可以直接使用。

三、适用场景

AI应用的实时信息获取

如果你的AI需要查询实时数据（比如股票价格、天气、新闻），可以用fetch_json来调用公开的API。或者用fetch_markdown来抓取网页内容，让AI基于最新信息回答问题。

内容整理与知识库构建

你可以用fetch_markdown将网页文章转换成干净的Markdown格式，然后保存到本地笔记软件（如Obsidian、Notion）中。这样你就拥有了一个离线的、格式统一的知识库。

数据采集与预处理

数据分析师可以用fetch_html获取原始页面，然后用fetch_txt提取纯文本用于NLP分析。或者用fetch_json直接从API获取结构化数据。

文档转换工作流

如果你需要批量将HTML文档转换成Markdown，可以用fetch_markdown工具配合脚本实现。比起手动复制粘贴或者使用在线转换工具，这要高效得多。

辅助爬虫开发

在编写爬虫之前，你可以先用fetch_html查看原始结构，用fetch_txt检查文本内容。这让开发和调试阶段更加便捷。

API的快速测试

开发者可以用fetch_json来快速测试一个API的返回结果，而不需要打开Postman或者写curl命令。在AI对话中直接完成测试和调试。

四、安装教程

前置准备

在使用之前，你需要确保系统安装了Node.js（版本14或更高）。你可以通过node -v来检查。如果没有安装，可以去Node.js官网下载LTS版本。

全局安装（推荐）

在终端中运行以下命令：

npm install -g @tokenizin/mcp-npx-fetch

安装完成后，你可以直接运行mcp-npx-fetch来启动服务器。但通常你不会直接运行，而是通过MCP客户端来调用它。

配置到Claude Desktop

这是最常用的集成方式。找到Claude Desktop的配置文件：

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

用文本编辑器打开这个文件，在mcpServers对象中添加以下配置：

{
  "mcpServers": {
    "fetch": {
      "command": "npx",
      "args": ["-y", "@tokenizin/mcp-npx-fetch"],
      "env": {}
    }
  }
}

如果你全局安装过，也可以直接使用mcp-npx-fetch命令：

{
  "mcpServers": {
    "fetch": {
      "command": "mcp-npx-fetch",
      "env": {}
    }
  }
}

配置到Cursor

在项目的根目录下创建或编辑.cursor/mcp.json文件：

{
  "mcpServers": {
    "fetch": {
      "command": "npx",
      "args": ["-y", "@tokenizin/mcp-npx-fetch"]
    }
  }
}

通过npx直接运行（无需安装）

如果你不想全局安装，也不介意为每个项目都下载一次，可以在配置中使用npx方式。上面Claude Desktop的配置示例已经展示了这一点。首次运行时会自动下载必要的包。

验证安装

配置完成后，重启你的AI客户端。然后输入：

“Use the fetch tool to get the markdown content of https://example.com”

如果配置成功，AI应该会调用fetch_markdown工具并返回网页内容。

五、使用示例

配置完成后，你可以用自然语言让AI获取和转换网络内容。以下是一些典型的用法。

示例一：获取Markdown格式的内容

这是最常用的场景。你可以让AI帮你抓取一篇文章，并转换成好读的Markdown。

“Fetch the content of https://en.wikipedia.org/wiki/Artificial_intelligence as markdown and then summarize the first paragraph.”

AI会调用fetch_markdown工具，返回格式良好的Markdown文本。由于Markdown本身就很容易阅读，AI可以直接基于它进行总结。

示例二：调用JSON API

很多公开数据是以JSON格式提供的。你可以让AI直接查询。

“Fetch the current Bitcoin price from the CoinDesk API (https://api.coindesk.com/v1/bpi/currentprice.json) as JSON, then extract the USD rate.”

AI会调用fetch_json工具，自动解析JSON响应，然后提取出你需要的信息。

示例三：获取纯文本进行内容分析

当你不需要格式，只关心文字内容时，fetch_txt是最佳选择。

“Fetch https://www.gutenberg.org/files/1342/1342-0.txt as plain text and tell me the first 500 characters.”

AI会返回干净的文本，可以直接用于分析。

示例四：使用自定义请求头

有些API需要认证。你可以让AI在请求时添加必要的头部。

“Fetch the JSON data from 'https://api.example.com/user' with an Authorization header 'Bearer YOUR_TOKEN'.”

AI会在调用fetch_json时附带你指定的请求头。

示例五：获取原始HTML进行分析

当你需要检查网页的原始结构时，可以用fetch_html。

“Fetch the HTML of https://example.com and tell me what the title tag is.”

AI会返回原始的HTML字符串，然后你可以让AI解析出特定的元素。

示例六：结合多个工具完成复杂任务

AI可以组合使用多个fetch工具。例如：

“First, fetch the markdown of https://example.com/blog. Then, fetch the HTML of https://example.com/about. Finally, compare the main topics of both pages.”

AI会依次调用fetch_markdown和fetch_html，然后基于结果进行对比分析。

六、常见问题

某些网页获取不到内容

可能的原因有几个：

• 目标网站需要特定的User-Agent。你可以通过自定义请求头来模拟真实的浏览器。例如：{ "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" }。
• 网站有反爬机制。这个工具是轻量级的，没有内置的反反爬措施。对于复杂的网站，建议使用更专业的工具（如Bright Data MCP）。
• 网站是SPA（单页应用），内容通过JavaScript动态加载。这个工具只获取初始HTML，不会执行JavaScript。对于这种情况，你需要使用支持浏览器渲染的工具。

Markdown转换效果不理想

Markdown转换的质量取决于源HTML的结构。如果转换后的格式混乱，可能是因为：

• 源网页的HTML结构本身就不规范。
• 某些复杂的布局（如多列、表格）在Markdown中无法完美表示。
• 你可以尝试先用fetch_txt获取纯文本，然后用其他方法处理。

JSON响应无法解析

确保URL确实返回的是有效的JSON。你可以先在浏览器中打开URL验证。如果确认是JSON但仍然无法解析，可能是响应中包含了BOM（Byte Order Mark）或其他特殊字符。目前工具没有做特殊处理，需要你自行处理。

请求超时

对于响应很慢的网站，可能会超时。目前的实现没有暴露超时配置参数。如果需要更长的等待时间，建议考虑其他支持超时设置的MCP服务器。

自定义请求头不生效

检查请求头的格式是否正确，应该是键值对的对象。注意，某些保留头部（如Host、Content-Length）可能被忽略。另外，确认你的AI客户端正确地传递了headers参数。

在Windows上遇到命令找不到错误

Windows对全局安装的可执行文件的路径解析有时有问题。可以尝试：

• 使用npx方式，而不是全局安装。
• 在配置中使用完整的node路径："command": "node", "args": ["C:\\Users\\你的用户名\\AppData\\Roaming\\npm\\node_modules\\@tokenizin\\mcp-npx-fetch\\dist\\index.js"]。

七、总结

mcp-npx-fetch是一个非常专注的工具。它不做爬虫，不做搜索，不做浏览器自动化。它只做一件事：从URL获取内容，然后以你需要的格式输出。这种专注使得它极其轻量、快速，而且几乎没有学习曲线。

我特别欣赏它的设计哲学。在MCP生态中，有很多大而全的服务器，提供几十个工具。但有时候，你只是需要一个简单的、可预测的、不依赖外部服务的解决方案。mcp-npx-fetch填补了这个空白。它只有41颗星，但并不意味着它不优秀。对于那些需要简单内容获取的场景，它可能是最合适的选择。

自定义请求头是一个关键的细节。这让它可以用于API认证，也可以模拟特定的浏览器环境，大大扩展了适用场景。Markdown转换的质量也相当不错，虽然不能保证100%完美，但已经能满足大多数日常需求。

当然，它也有一些局限性。它不处理JavaScript渲染的内容，不解决反爬虫问题，没有内置的重试机制。但对于它的定位（简单、快速、本地转换），这些都不是缺陷，而是设计选择。

如果你是开发者，需要为AI应用添加最简单的网络获取能力，mcp-npx-fetch值得试试。有时候，最简单的解决方案就是最好的解决方案。