使用说明

Markdown MCP服务器

一种模型上下文协议（MCP）服务器，使用Playwright从网页中提取干净的标记内容。此服务器提供 get_page_markdown 该工具可以从任何URL中提取主要内容，同时过滤掉导航、页眉、页脚和其他非内容元素。

特性

🎯 智能内容提取：自动识别和提取网页中的主要内容
🧹 清洁输出：过滤掉导航、页眉、页脚、侧边栏和广告
🎨 丰富的Markdown：保留格式，包括标题、粗体、斜体、代码块、列表和表格
🖼️ 图像支持：可选地在markdown中包含图像引用
🔗 链接支持：可选择在markdown中包含超链接
⚡ 快速可靠：使用Playwright进行强大的网页抓取
🔄 动态内容：处理JavaScript繁重的网站和动态内容加载
🛡️ 错误处理：使用回退提取方法进行稳健的错误处理

安装

克隆或下载此存储库：

git clone <repository-url>
cd markdown-mcp

安装依赖项：
```
npm install
```
安装Playwright浏览器：
```
npx playwright install chromium
```
使脚本可执行（可选）：
```
chmod +x markdown-mcp.js
```

用法

作为MCP服务器

启动服务器：

node markdown-mcp.js

服务器提供了一个工具： get_page_markdown

刀具参数

url （必填）：从中提取markdown的URL
includeImages （可选，默认值：true）：是否在markdown中包含图像引用
includeLinks （可选，默认值：true）：是否在markdown中包含超链接
waitForSelector （可选）：提取内容之前要等待的CSS选择器（对动态内容有用）
timeout （可选，默认值：30000）：导航超时（毫秒）

示例用法

{
  "name": "get_page_markdown",
  "arguments": {
    "url": "https://docs.confluent.io/cloud/current/flink/operate-and-deploy/monitor-statements.html",
    "includeImages": true,
    "includeLinks": true,
    "timeout": 30000
  }
}

高级使用示例

从特定部分提取内容：

{
  "name": "get_page_markdown",
  "arguments": {
    "url": "https://example.com/article",
    "waitForSelector": ".main-content",
    "includeImages": false,
    "includeLinks": true
  }
}

使用自定义超时提取内容：

{
  "name": "get_page_markdown",
  "arguments": {
    "url": "https://slow-loading-site.com",
    "timeout": 60000
  }
}

文件结构

此项目包括为不同客户端优化的两个MCP服务器文件：

markdown-mcp.js -针对Claude Desktop进行了优化
markdown-mcp-gemini.js -针对Gemini CLI进行了优化

两个文件提供的内容相同 get_page_markdown 工具，但配置不同，以实现每个客户端的最佳性能。

添加到AI客户端

此MCP服务器可以与支持模型上下文协议的多个AI客户端一起使用。下面是最受欢迎的客户的说明。

Claude桌面集成

要将此MCP服务器与Claude Desktop一起使用，您需要将其添加到Claude Desktop配置文件中。

步骤1：找到Claude桌面配置

macOS：

配置文件： ~/Library/Application Support/Claude/claude_desktop_config.json

窗户：

配置文件： %APPDATA%\Claude\claude_desktop_config.json

Linux：

配置文件： ~/.config/claude/claude_desktop_config.json

步骤2：编辑配置文件

打开配置文件 在文本编辑器中
添加markdown mcp服务器 到 mcpServers 章节
更新路径 指向你的 markdown-mcp.js 文件

步骤3：配置示例

macOS配置

{
  "mcpServers": {
    "markdown-mcp": {
      "command": "node",
      "args": ["/Users/yourusername/path/to/markdown-mcp/markdown-mcp.js"],
      "env": {}
    }
  }
}

Windows配置

{
  "mcpServers": {
    "markdown-mcp": {
      "command": "node",
      "args": ["C:\\Users\\YourUsername\\path\\to\\markdown-mcp\\markdown-mcp.js"],
      "env": {}
    }
  }
}

Linux配置

{
  "mcpServers": {
    "markdown-mcp": {
      "command": "node",
      "args": ["/home/yourusername/path/to/markdown-mcp/markdown-mcp.js"],
      "env": {}
    }
  }
}

步骤4:重新启动克劳德桌面

更新配置文件后，重新启动Claude Desktop以使更改生效。

步骤5：验证安装

打开克劳德桌面
开始新的对话
尝试让Claude使用markdown mcp工具从网页中提取内容
示例：“使用markdown mcp从中提取内容https://example.com"

故障排除

如果MCP服务器不工作：

检查文件路径 -确保路径 markdown-mcp.js 正确且文件存在
验证Node.js -确保Node.js已安装并可从命令行访问
检查权限 -确保脚本具有执行权限
手动测试 -试着跑步 node markdown-mcp.js 在终端中查看是否有任何错误
检查克劳德桌面日志 -在Claude Desktop的开发人员控制台中查找错误消息

常见问题：

未找到路径：仔细检查配置中的文件路径
找不到Node.js：确保Node.js已安装并位于PATH中
权限不足：运行 chmod +x markdown-mcp.js 使脚本可执行
缺少依赖项：运行 npm install 在markdown mcp目录中

Gemini CLI集成

要将此MCP服务器与Gemini CLI一起使用，请执行以下步骤：

步骤1：安装Gemini CLI

如果您尚未安装Gemini CLI：

npm install -g @google/gemini-cli

验证安装：

gemini --version

步骤2：将MCP服务器添加到Gemini CLI

将您的markdown mcp服务器添加到Gemini CLI：

gemini mcp add markdown-mcp /Users/yourusername/path/to/markdown-mcp/markdown-mcp-gemini.js

重要提示： 替换 /Users/yourusername/path/to/markdown-mcp/markdown-mcp-gemini.js 与您的实际路径 markdown-mcp-gemini.js 文件。

步骤3：验证集成

列出所有已配置的MCP服务器以验证集成：

gemini mcp list

你应该看看 markdown-mcp 列在服务器中。

步骤4：测试集成

使用Gemini CLI测试markdown mcp服务器：

# Example: Extract content from a webpage
gemini "Use the markdown-mcp tool to extract content from https://example.com"

或者您可以直接使用该工具：

# If the tool is exposed as a command
gemini get_page_markdown "https://example.com"

步骤5：完成示例-提取并保存Markdown

以下是一个完整的示例，用于提取markdown内容并将其保存到文件中：

# Extract content from a webpage and save to result.md
gemini "Use get_page_markdown to extract content from https://www.confluent.io/blog/event-driven-flink-agents-enterprise-ai/ and save the response as result.md"

此命令将：

使用 get_page_markdown 从Confluent博客文章中提取干净的降价内容的工具
将提取的markdown内容保存到名为的文件中 result.md 在当前目录中
为您提供网页内容的干净、可读的降价版本

其他示例：

# Extract content from documentation and save with custom filename
gemini "Use get_page_markdown to extract content from https://docs.confluent.io/cloud/current/flink/operate-and-deploy/monitor-statements.html and save it as flink-docs.md"

# Extract content from a GitHub repository README
gemini "Use get_page_markdown to extract content from https://github.com/microsoft/vscode and save as vscode-readme.md"

# Extract content with specific options
gemini "Use get_page_markdown with includeImages=false to extract content from https://example.com and save as clean-content.md"

Gemini CLI故障排除

如果MCP服务器无法与Gemini CLI配合使用：

检查文件路径 -确保路径 markdown-mcp-gemini.js 是正确和绝对的
验证Node.js -确保Node.js可以从命令行访问
检查权限 -确保脚本具有执行权限(chmod +x markdown-mcp-gemini.js)
手动测试服务器 -快跑 node markdown-mcp-gemini.js 检查错误
检查Gemini CLI日志 -在Gemini CLI输出中查找错误消息

常见的Gemini CLI问题：

未找到路径：添加MCP服务器时使用绝对路径
权限不足：运行 chmod +x markdown-mcp-gemini.js 使脚本可执行
找不到Node.js：确保Node.js已安装并位于PATH中
服务器未响应：检查服务器是否正确启动 node markdown-mcp-gemini.js

与多个AI客户端一起使用

您可以将同一个markdown mcp服务器与多个AI客户端同时使用。MCP服务器旨在高效地处理多个并发请求。

多客户端设置的好处

灵活性：对不同的AI模型使用相同的工具
效率：跨客户端共享同一服务器实例
一致性：无论使用何种AI客户端，都能获得相同的提取质量
资源优化：无需运行多个服务器实例

为多个客户端设置

设置Claude桌面 使用 markdown-mcp.js （如上所述）
设置Gemini CLI 使用 markdown-mcp-gemini.js （如上所述）
两个客户端都可以使用各自的服务器文件 -针对每个客户端进行了优化

使用示例

使用克劳德桌面：

Use markdown-mcp to extract content from https://docs.confluent.io/cloud/current/flink/operate-and-deploy/monitor-statements.html

使用Gemini CLI：

# Extract and save to file
gemini "Use get_page_markdown to extract content from https://docs.confluent.io/cloud/current/flink/operate-and-deploy/monitor-statements.html and save as result.md"

# Or just extract without saving
gemini "Use get_page_markdown to extract content from https://docs.confluent.io/cloud/current/flink/operate-and-deploy/monitor-statements.html"

性能注意事项

服务器高效地处理多个并发请求
每个请求都使用新的浏览器上下文以确保安全
内存使用量随并发请求的数量而变化
典型响应时间：每个请求5-15秒

测试

服务器已经过测试和验证，可以与各种网站正常工作，包括：

✅ 文件网站 （Confluent、GitHub等）
✅ 新闻文章 博客文章
✅ 技术文档 附带代码示例
✅ 电子商务页面 以及产品说明
✅ JavaScript密集型网站 具有动态内容

测试功能

✅ 摘录标题、段落和文本内容
✅ 保留粗体和斜体格式
✅ 处理代码块和内联代码
✅ 进程列表（有序和无序）
✅ 提取格式正确的表
✅ 过滤掉导航和页脚内容
✅ 处理图像和链接（启用时）
✅ 响应MCP协议请求
✅ 适用于动态内容和JavaScript密集型网站

手动测试

您可以通过运行以下命令手动测试服务器：

# Test with a simple URL
node -e "
const { spawn } = require('child_process');
const server = spawn('node', ['markdown-mcp.js'], { stdio: ['pipe', 'pipe', 'pipe'] });
const request = {
  jsonrpc: '2.0',
  id: 1,
  method: 'tools/call',
  params: {
    name: 'get_page_markdown',
    arguments: { url: 'https://example.com' }
  }
};
server.stdin.write(JSON.stringify(request) + '\n');
setTimeout(() => {
  server.kill();
  console.log('Test completed');
}, 10000);
"

支持的网站

此MCP服务器适用于：

文件网站：Confluent、GitHub、GitLab等。
新闻和博客：大多数主要新闻网站和博客
技术内容：堆栈溢出，中等，Dev.to
电子商务：产品页面和说明
学术内容：研究论文和文章
社交媒体：推特帖子、领英文章

演出

典型提取时间：5-15秒，取决于页面复杂性
内存使用：每次提取约50-100MB
支持的内容大小：高达数MB的文本内容
并发请求：高效处理多个请求

需求

Node.js：版本18或更高版本
剧作家：Chromium浏览器（自动安装）
记忆：至少512MB可用RAM
磁盘空间：Playwright浏览器约200MB

安全考虑

为了安全起见，服务器以无头模式运行
不存储Cookie或持久数据
每个请求都使用一个新的浏览器上下文
网络请求受到超时设置的限制
没有记录或存储敏感数据

贡献

分叉存储库
创建要素分支
进行更改
彻底测试
提交拉取请求

支持

如果您遇到问题：

检查上面的故障排除部分
验证是否满足所有要求
首先使用简单的URL进行测试
检查Claude Desktop日志中的错误消息
打开一个包含详细错误信息的问题