Skip to main content

​
概览

Web2MD MCP server 把 Web2MD 封装成一组工具，供 AI 助手直接调用，基于 Model Context Protocol (MCP)——一个连接 AI 模型与外部工具、数据源的开放标准。 配置完成后，你可以在对话中直接让 Claude、Cursor 或 Windsurf 转换页面、搜索并同步你的 Library、用 Chrome 扩展批量转换，或调用一个已保存的 Skill——全程无需离开对话窗口。
MCP server 需要一个 Web2MD API key（PRO 套餐）。可以从控制台生成一个，或运行 npx web2md-cli login 完成一次认证，密钥会自动与 CLI 共享（见下方认证）。

​
可用工具

MCP server 提供 11 个工具，按功能分组如下：

​
convert_url

在服务端抓取一个 URL，将页面内容转为 Markdown 返回，同时附带标题、字数和阅读时长。支持与 REST API 相同的转换选项（includeImages、includeLinks）。 示例提示词： “把这个 URL 转成 markdown：https://docs.example.com/getting-started”

​
bridge_convert_url

通过你正在运行的 Chrome 扩展（经本地 HTTP bridge）抓取 URL 的 HTML，再在服务端把 HTML 转成 Markdown。适用于服务端无法直接访问的页面——Reddit、需要登录的站点，或大量依赖 JS 渲染的页面。需要 Chrome 已打开且安装了 Web2MD 扩展；扩展 ID 会根据你的 API key 自动发现。 示例提示词： “用 bridge 转换这个 Reddit 帖子：https://reddit.com/r/…“

​
agent_convert

与 bridge_convert_url 一样通过你的 Chrome 扩展转换 URL，但走的是 Agent Bridge 的 native-messaging 通道而非 HTTP。可以传入可选的 skill 参数：传入一个 Skill 的 id 或名称，其内容会附加在返回的 Markdown 后面，方便 agent 立即据此行动。需要 Chrome 已运行，且已安装扩展和 native host。 示例提示词： “用 summarize 这个 skill 转换这个页面：https://…“

​
agent_batch_convert

传输方式与 agent_convert 相同，但接受一个最多 50 个 URL 的数组，在一次调用中依次转换。适合一次性拉取多个 Reddit 帖子或 JS 渲染页面。 示例提示词： “批量转换这 12 个 URL 为 Markdown：[…]“

​
search_library

按关键词（匹配标题和全文内容）和/或标签搜索你的 Web2MD Library——即你保存过的每一个页面，按最新排序。返回精简的元数据（id、标题、url、日期、标签），而非完整 Markdown。免费套餐账户只能看到最近的结果；结果被截断时工具会提示你。 示例提示词： “在我的 library 里搜索关于 authentication 的内容”

​
get_library_items

按 id 获取 Library 条目的完整 Markdown 内容（每次调用最多 20 条——先用 search_library 找到 id）。返回内容可能很大；对于长页面，建议每次调用不超过 5 个 id。 示例提示词： “获取 library 条目 abc123 和 def456 的完整内容”

​
sync_library

把你整个 Library 同步到本地目录，存为带 frontmatter 的 Markdown 文件，按标签组织。默认是增量同步（在 <dir>/.web2md-sync.json 中追踪游标）；传入 full: true 可重新扫描全部内容。这与 CLI 中 web2md sync 运行的同步逻辑相同——选择适合你工作流的方式即可。 示例提示词： “把我的 library 同步到 ~/notes/web2md，只要 ‘research’ 标签的内容”

​
list_skills

以精简数组形式（id、名称、描述）列出你 Web2MD 云账户中保存的所有 Skill。用 get_skill 获取某一个的完整内容。 示例提示词： “我保存了哪些 skill？“

​
get_skill

按 id 或名称获取一个 Skill 的完整 SKILL.md 风格内容——包括它的指令、描述和全部内容。如果不知道 id，先用 list_skills。 示例提示词： “获取我的 ‘summarize’ skill”

​
semantic_search / get_conversion（已废弃）

这两个工具早于 Library 存在。它们仍可使用，但只能看到通过旧版历史记录 API 保存的转换记录，看不到完整的 Library——新集成应该改用 search_library 和 get_library_items。

​
认证

Server 按以下顺序解析 API key：
  1. 环境变量 WEB2MD_API_KEY（如果已设置）。
  2. 否则读取 ~/.web2md/config.json——这个文件由 npx web2md-cli login（CLI 的设备登录流程）写入。运行一次 login，CLI 和 MCP server 就都会自动读取到密钥，无需配置 env 块。
如果两者都没有找到，server 仍会启动，但每次工具调用都会返回认证错误，并提示你设置密钥或运行 login。

​
设置

打开你的 Claude Desktop 配置文件：
  • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows： %APPDATA%\Claude\claude_desktop_config.json
在 mcpServers 下添加 web2md 条目：
如果你已经运行过 npx web2md-cli login，可以直接去掉 env 块——server 会从 ~/.web2md/config.json 读取密钥。重启 Claude Desktop。你应该能在工具选择器里看到 Web2MD 的工具。

​
使用示例

MCP server 运行起来之后，你可以在 AI 助手里用自然语言交流：
你： 把这个 URL 转成 markdown：https://react.dev/learn/thinking-in-react助手： （调用 convert_url） 这是 “Thinking in React” 转换后的 Markdown……
你： 在我的 library 里搜索关于 authentication 的内容，然后获取最新那条的完整内容助手： （调用 search_library，然后 get_library_items） 我找到了 3 条与 authentication 相关的内容。这是最新一条 “OAuth 2.0 Guide” 的完整内容……
你： 把我的 library 同步到 ~/notes/web2md助手： （调用 sync_library） 已同步 42 条新内容，118 条已是最新，0 条失败。
你： 批量转换这 8 个 Reddit 帖子：[…]助手： （调用 agent_batch_convert） 已成功转换 8/8 个 URL。
你： 我有哪些 skill？能不能对这个页面应用 “summarize”：https://…助手： （调用 list_skills，然后调用 agent_convert 并传入 skill: "summarize"） 这是转换成 Markdown 的页面，下面附上了应用 summarize skill 后的结果……
可以在同一次对话中组合使用多个工具。例如：“在我的 library 里搜索 React 相关文档，然后获取最新那条的完整内容。“

​
故障排查

确认你在修改配置文件后重启了应用。检查 npx -y web2md-mcp-server 是否能在终端里正常运行。
确认 WEB2MD_API_KEY 是一个有效的 w2m_ 密钥，或 ~/.web2md/config.json 中存在有效密钥（不确定的话重新运行 npx web2md-cli login）。你可以在 API keys 页面核实你的密钥。
这些工具需要 Chrome 已打开并安装了 Web2MD 扩展，agent_* 工具还需要安装 native host。设置方法见 Agent Bridge。
可以先尝试全局安装：npm install -g web2md-mcp-server，然后把 command 改成 web2md-mcp-server 并去掉 args 字段。