URL to Markdown (Article Extractor)

url-to-markdown-mcp

npm： @kitedesk-erm/url-to-markdown-mcp · 官方 MCP Registry： io.github.kitedesk-erm/url-to-markdown-mcp

一个 MCP 服务，可将任意 URL 转换为简洁的 Markdown 或纯文本，供 AI 助手使用。 它为 Claude、Cursor、Windsurf、Cline、VS Code Copilot 及其他 MCP 客户端提供一个工具：extract_url。该工具会抓取网页，并仅返回主要内容（不含导航栏、广告、Cookie 横幅、侧边栏、页脚或评论），以及标题、作者、发布日期、字数和阅读时间。

它由托管在 Zyla API Hub 上的 Article Extractor and URL to Markdown API 提供支持。你需要一个 Zyla API 密钥，可获取 7 天免费试用。

• 速度快：提取速度 p50 约为 230 ms，p95 约为 650 ms（对 20 个真实文章 URL 的测量结果，测于 2026-10-22）
• 适用于 LLM 的 Markdown，包含标题、列表、代码块和绝对链接；max_chars 可帮助你控制在令牌预算内
• 只读且可防范 SSRF：拒绝 localhost 和私有 IP
• 轻量：一个工具、stdio 传输，以及两个运行时依赖项（@modelcontextprotocol/sdk 和 zod）

工具

extract_url

参数	类型	默认值	说明
url	string，必填		公共 http(s) URL（可省略 scheme）
format	markdown | text | both	markdown	输出格式
max_chars	integer	无限制	将内容截断至 N 个字符
links	boolean	true	保留 [text](url) 链接
images	boolean	false	包含  图片

该工具会先返回简短的元数据标题，然后是内容：

# How to Work Hard
Source: https://paulgraham.com/hwh.html
Words: 3313 (~14 min read) | truncated by max_chars

June 2021

It might not seem there's much to learn about how to work hard. Anyone who's been to school knows what it entails, ...

错误会以 MCP 工具错误（isError: true）的形式返回，并附带易读的消息，让模型能够恢复。这包括缺少密钥、私有或 localhost URL、非 HTML 目标、网站无法访问、Zyla 配额或速率限制，以及 API 的 502 错误：upstream_blocked（网站返回 401/403/429/451 或机器人验证页面）和 empty_content（字数约为 0，例如由客户端渲染的页面）。Zyla 仅对成功的调用收费，因此被拦截或内容为空的页面不会收费。

安装

你需要 Node.js 18 或更高版本。所有客户端都运行同一条命令 npx -y @kitedesk-erm/url-to-markdown-mcp，并在 ZYLA_API_KEY 中设置你的密钥。

Claude Desktop

编辑 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/；Windows：%APPDATA%\Claude\）：

{
  "mcpServers": {
    "url-to-markdown": {
      "command": "npx",
      "args": ["-y", "@kitedesk-erm/url-to-markdown-mcp"],
      "env": { "ZYLA_API_KEY": "your-zyla-api-key" }
    }
  }
}

Claude Code

claude mcp add url-to-markdown --env ZYLA_API_KEY=your-zyla-api-key -- npx -y @kitedesk-erm/url-to-markdown-mcp

Cursor

全局配置请使用 ~/.cursor/mcp.json，单个项目配置请使用 .cursor/mcp.json：

{
  "mcpServers": {
    "url-to-markdown": {
      "command": "npx",
      "args": ["-y", "@kitedesk-erm/url-to-markdown-mcp"],
      "env": { "ZYLA_API_KEY": "your-zyla-api-key" }
    }
  }
}

VS Code（GitHub Copilot Agent 模式）

将以下内容添加到 .vscode/mcp.json。VS Code 会提示输入密钥并安全存储：

{
  "inputs": [
    { "type": "promptString", "id": "zyla-key", "description": "Zyla API key", "password": true }
  ],
  "servers": {
    "url-to-markdown": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@kitedesk-erm/url-to-markdown-mcp"],
      "env": { "ZYLA_API_KEY": "${input:zyla-key}" }
    }
  }
}

Windsurf、Cline、Continue、Zed 及其他客户端

大多数客户端使用与 Claude Desktop 和 Cursor 相同的 mcpServers 配置块（Windsurf 使用 ~/.codeium/windsurf/mcp_config.json；Cline 使用其 MCP Servers → Configure 面板）。通用形式如下：

• command： npx
• args： ["-y", "@kitedesk-erm/url-to-markdown-mcp"]
• env： ZYLA_API_KEY=<your key>
• transport： stdio

Smithery / Docker

仓库中包含 smithery.yaml 和 Dockerfile。你也可以在 Docker 中运行：docker build -t url-to-markdown-mcp . && docker run -i --rm -e ZYLA_API_KEY url-to-markdown-mcp。

从源代码构建

如果你在 npm 发布前安装，请从源代码构建：

git clone https://github.com/kitedesk-erm/url-to-markdown-mcp.git
cd url-to-markdown-mcp && npm install && npm run build
# then use "command": "node", "args": ["/absolute/path/to/url-to-markdown-mcp/dist/index.js"]

示例提示词

• “阅读 https://go.dev/blog/go1.22 并总结循环方面的变化。”
• “提取这三篇文章的文本并比较它们的论点”（每篇文章设置 max_chars: 6000）。
• “将此页面保存为 Markdown 笔记，并添加标题和作者的 front matter。”

限制

• 不支持 JavaScript 渲染。仅在浏览器中构建内容的页面（部分 SPA）返回的文本很少。
• 需要付费或受机器人防护的网站只会返回其公开提供的内容。被拦截或质询的请求会返回 upstream_blocked 工具错误，且不会计费。
• 你的 Zyla 套餐决定配额和速率限制。只有成功的（200）调用才会计入套餐用量。

开发

npm install
npm test          # build, then the raw JSON-RPC handshake + tools/list, a tool call via a local mock Zyla gateway, and metadata checks
npm run test:live # same, but the mock gateway forwards to the live extraction backend

测试使用针对本地模拟服务的虚假密钥，因此不需要或存储真实密钥。Zyla 端点位于一个常量中：src/config.ts。ZYLA_ENDPOINT 可以覆盖此端点，但仅用于测试。

更改 GitHub 用户名或命名空间： package.json 中的 mcpName 是唯一可信来源。运行 npm run set-github-handle -- <handle> 可重写 package.json、server.json、README.md 和 smithery.yaml。随后，npm test 会检查它们是否一致；MCP Registry 也要求这些文件保持一致。

相关项目

• url-to-markdown-api：零依赖的 JS/TS 和 Python 客户端，以及 RAG、Agent 和稍后阅读示例
• Zyla 列表：Article Extractor and URL to Markdown API

许可证

MIT