HTML到图像MCP服务器
一个复杂的模型上下文协议（MCP）服务器，可以捕获网页的高质量屏幕截图，并自动将其上传到Cloudinary，以便于共享和存储。
🌟 特性
- 📸 网页截图：捕获任何可公开访问的网页的全分辨率屏幕截图
- ☁️ 云集成：使用安全URL自动上传到Cloudinary
- 🎨 可定制尺寸：配置视口宽度和高度以实现完美捕捉
- 📄 完整页面支持：捕获视口外整个页面高度的选项
- 🚀 高性能：内置async/await以获得最佳速度
- 🔒 安全：API凭据的基于环境的配置
- 🐳 Docker就绪：容器化部署支持
🛠️ 安装
先决条件
安装前，请确保：
- Python 3.8或更高版本
- Cloudinary帐户(免费注册)
- Docker（可选，用于容器化部署）
快速设置
- 克隆存储库:
git clone git@github.com:alperenkocyigit/html-to-image-mcp.git
cd html-to-image-mcp- 安装依赖项:
pip install -r requirements.txt- 下载Chromium浏览器:
python setup.py- 配置环境变量:
创建一个 .env 项目根目录中的文件：
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secretDocker安装
- 构建Docker镜像:
docker build -t html-to-image-mcp .- 使用环境变量运行:
docker run -e CLOUDINARY_CLOUD_NAME=your_cloud_name \
-e CLOUDINARY_API_KEY=your_api_key \
-e CLOUDINARY_API_SECRET=your_api_secret \
html-to-image-mcp🚀 用法
通过Smithery轻松安装
参观铁匠铺并遵循指示
https://smithery.ai/server/@alperenkocygit/html到图像mcp
启动MCP服务器
地方发展（STDIO模式）
MCP_TRANSPORT=stdio python server.py服务器将在STDIO传输上运行，用于本地开发和测试。
用于HTTP部署（流式HTTP模式）
python server.py服务器将在HTTP传输（可流式传输HTTP）上运行 http://0.0.0.0:8000，适用于容器部署和Smithery等托管环境。MCP端点位于 /mcp.
工具： take_screenshot
捕获网页的屏幕截图并将其上传到Cloudinary。
参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
url | string | ✅ 是 | - | 要截图的网页的URL。必须从以下内容开始 https:// 或 http:// |
width | 整数 | ❌ 可选 | 1280 | 视口宽度（像素） |
height | 整数 | ❌ 可选 | 720 | 视口高度（像素） |
fullPage | boolean | ❌ 可选 | false | 捕获整页高度，而不是仅捕获视口高度 |
示例用法
基本截图:
{
"name": "take_screenshot",
"arguments": {
"url": "https://example.com"
}
}自定义尺寸:
{
"name": "take_screenshot",
"arguments": {
"url": "https://github.com",
"width": 1920,
"height": 1080
}
}完整页面捕获:
{
"name": "take_screenshot",
"arguments": {
"url": "https://news.ycombinator.com",
"width": 1280,
"height": 720,
"fullPage": true
}
}响应格式
{
"status": 200,
"message": "Screenshot captured and uploaded successfully",
"url": "",
"public_id": "screenshots/abc123",
"dimensions": {
"width": 1280,
"height": 720,
"fullPage": false
}
}⚙️ 配置
环境变量
| 变量 | 描述 | 必填 |
|---|---|---|
CLOUDINARY_CLOUD_NAME | 您的Cloudinary云名称 | ✅ |
CLOUDINARY_API_KEY | 您的Cloudinary API密钥 | ✅ |
CLOUDINARY_API_SECRET | 您的Cloudinary API秘密 | ✅ |
Cloudinary设置
- 创建Cloudinary帐户 在 cloudinary.com
- 获取您的凭据 从仪表板：
- 云名称 - API密钥 - API秘密
- 添加凭据 给你的
.env文件或环境变量
🏗️ 建筑
graph TB
subgraph "MCP Client Environment"
A[MCP Client
Claude/VS Code/etc] --> B[JSON-RPC Request
take_screenshot]
end
subgraph "HTML to Image MCP Server"
B --> C{URL Validation}
C -->|Valid URL| D[Pyppeteer
Browser Launch]
C -->|Invalid URL| E[Error Response
Invalid URL format]
D --> F[Headless Chromium
Browser Instance]
F --> G[Page Navigation
viewport: width x height]
G --> H[Screenshot Capture
PNG format]
H --> I[Temporary File
Creation]
I --> J[Cloudinary Upload
folder: screenshots]
end
subgraph "External Services"
K[Target Website
https://example.com]
L[Cloudinary CDN
Image Storage]
end
subgraph "Response Flow"
J --> M[Upload Success]
M --> N[JSON Response
secure_url, public_id]
N --> O[MCP Client
Receives Image URL]
end
G --> K
J --> L
%% Error paths
G -->|Navigation Timeout| P[Error Response
Navigation failed]
J -->|Upload Failed| Q[Error Response
Cloudinary upload failed]
%% Styling
classDef client fill:#e1f5fe
classDef server fill:#f3e5f5
classDef external fill:#e8f5e8
classDef error fill:#ffebee
class A,O client
class C,D,F,G,H,I,J,M,N server
class K,L external
class E,P,Q error关键组件
- MCP服务器：处理协议通信和请求路由
- 皮影师：控制无头Chromium进行屏幕截图
- Cloudinary SDK：管理图像上传和存储
- 码头工人：提供一致的部署环境
🔧 发展
项目结构
html-to-image-mcp/
├── server.py # Main MCP server implementation
├── app.py # Utility functions for screenshot capture
├── setup.py # Chromium download and setup
├── requirements.txt # Python dependencies
├── Dockerfile # Container configuration
├── smithery.yaml # Smithery deployment config
└── README.md # This documentation运行测试
# Test Chromium installation
python setup.py
# Test screenshot functionality
python -c "
import asyncio
from app import url_to_cloudinary_url_async
print(asyncio.run(url_to_cloudinary_url_async('https://example.com')))
"添加功能
- 分叉存储库
- 创建要素分支:
git checkout -b feature-name - 进行更改
- 彻底测试
- 提交拉取请求
🐳 Docker部署
建筑
docker build -t html-to-image-mcp .跑步
docker run -d \
--name html-to-image \
-p 8000:8000 \
-e CLOUDINARY_CLOUD_NAME=your_cloud_name \
-e CLOUDINARY_API_KEY=your_api_key \
-e CLOUDINARY_API_SECRET=your_api_secret \
html-to-image-mcp服务器将可在以下位置访问 http://localhost:8000 用于HTTP/SSE传输。
Docker Compose
version: '3.8'
services:
html-to-image-mcp:
build: .
ports:
- "8000:8000"
environment:
- CLOUDINARY_CLOUD_NAME=your_cloud_name
- CLOUDINARY_API_KEY=your_api_key
- CLOUDINARY_API_SECRET=your_api_secret
restart: unless-stopped🚨 故障排除
常见问题
“Chromium下载失败”
# Install required system dependencies (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y \
gconf-service libasound2 libatk1.0-0 libc6 libcairo2 libcups2 \
libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 \
libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 \
libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 \
libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 \
libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 \
libxtst6 ca-certificates fonts-liberation libappindicator1 \
libnss3 lsb-release xdg-utils wget“URL格式无效”
- 确保URL以开头
https://或http:// - 检查网站是否可公开访问
- 验证URL中没有拼写错误
“云上传失败”
- 验证您的Cloudinary凭据是否正确
- 检查您的Cloudinary帐户限制
- 确保您的API密钥具有上载权限
“导航超时”
- 增加服务器配置中的超时时间
- 检查目标网站是否响应
- 验证您的互联网连接
性能提示
- 使用较小的视口大小以实现更快的捕获
- 启用
fullPage: false为了获得更好的性能 - 考虑缓存频繁访问的屏幕截图
- 监控Cloudinary使用限制
📚 API 参考
URL验证
服务器验证URL以确保它们：
- 从开始
https://或http:// - 具有有效的域结构
- 根据RFC标准正确格式化
屏幕截图选项
- 视口大小：控制浏览器窗口大小
- 整页：捕获初始视口之外的内容
- PNG格式：始终输出高质量的PNG图像
- 网络空闲：等待网络请求完成
错误处理
服务器为以下对象提供详细的错误消息：
- URL无效或缺失
- 网络连接问题
- Cloudinary上传失败
- 浏览器自动化问题
📝 许可证
此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。
🤝 贡献
欢迎投稿！请随时提交拉取请求。对于重大更改，请先打开一个问题来讨论您想要更改的内容。
📞 支持
- 问题：报告GitHub问题上的错误
- 文档：查看此README以获取全面的指南
- 社区：在GitHub讨论中加入讨论
______________________________________________________________________
Alperen Koçyiğit与❤️ 对于MCP社区