SVG Converter
Convert SVG files to PNG, ICO, and JPG formats with high-quality rendering using the Cairo C library.
SVG 转换器 FastMCP 服务
一个基于 FastMCP 的专业 SVG 文件转换服务包，提供完整的 SVG 转换功能。支持将 SVG 转换为 PNG、ICO、JPG 等格式，优先使用 Cairo C库 进行高质量渲染，特别优化了中文字符的显示效果。
🎨 支持的输出格式
| 格式 | 扩展名 | 透明支持 | 适用场景 | 推荐用途 |
|---|---|---|---|---|
| PNG | .png | ✅ | 图标、图形、UI元素 | 推荐格式，质量最佳 |
| ICO | .ico | ✅ | 应用程序图标 | Windows 图标文件 |
| JPG/JPEG | .jpg, .jpeg | ❌ | 照片、复杂图像 | 文件较小，不支持透明 |
🏗️ 项目架构
graph TB
subgraph "MCP 客户端层"
A[MCP 客户端<br/>Claude Desktop/其他]
B[HTTP 客户端<br/>Web 应用]
C[SSE 客户端<br/>实时应用]
end
subgraph "FastMCP 服务层"
D[FastMCP 框架]
E[STDIO 传输]
F[HTTP 传输]
G[SSE 传输]
end
subgraph "工具函数层"
H[convert_svg_file<br/>文件转换]
I[convert_svg_string<br/>字符串转换]
J[batch_convert_svg_files<br/>批量转换]
K[get_converter_engine_info<br/>引擎信息]
L[get_svg_file_info<br/>文件信息]
M[get_svg_string_info<br/>字符串信息]
end
subgraph "核心转换层"
N[SVGConverter 类]
O[Cairo C库 引擎]
P[SVGLib 引擎]
Q[PIL 引擎]
R[混合渲染引擎]
end
A -.->|JSON-RPC| E
B -.->|HTTP API| F
C -.->|Server-Sent Events| G
E --> D
F --> D
G --> D
D --> H
D --> I
D --> J
D --> K
D --> L
D --> M
H --> N
I --> N
J --> N
K --> N
L --> N
M --> N
N --> O
N --> P
N --> Q
N --> R
style A fill:#e3f2fd
style B fill:#e3f2fd
style C fill:#e3f2fd
style D fill:#fff3e0
style N fill:#f3e5f5
style O fill:#e8f5e8
style P fill:#e8f5e8
style Q fill:#e8f5e8
style R fill:#e8f5e8
� SVG 转换流程
flowchart TD
A[SVG 输入] --> B{检测内容类型}
B -->|包含中文字符| C[混合渲染模式]
B -->|纯英文/图形| D[标准引擎模式]
C --> C1[Cairo/SVGLib 渲染基础图形]
C1 --> C2[PIL 覆盖渲染中文文字]
C2 --> E[图像后处理]
D --> D1{选择转换引擎}
D1 -->|优先| D2[Cairo C库]
D1 -->|备选| D3[SVGLib + ReportLab]
D1 -->|后备| D4[PIL 直接渲染]
D2 --> E
D3 --> E
D4 --> E
E --> F{输出格式}
F -->|PNG| G[PNG 输出<br/>支持透明背景]
F -->|ICO| H[ICO 输出<br/>图标格式]
F -->|JPG| I[JPG 输出<br/>照片格式]
G --> J[转换完成]
H --> J
I --> J
style A fill:#e1f5fe
style J fill:#c8e6c9
style C fill:#fff3e0
style D fill:#f3e5f5
🚀 安装方法
方法一：从 GitHub 安装（推荐）
# 直接从 GitHub 安装最新版本
pip install git+https://github.com/RusianHu/svg-converter-tools-mcp.git -i https://pypi.tuna.tsinghua.edu.cn/simple/
# 安装完整版本（包含所有可选依赖）
pip install "git+https://github.com/RusianHu/svg-converter-tools-mcp.git[full]" -i https://pypi.tuna.tsinghua.edu.cn/simple/
方法二：从源码安装
# 克隆仓库
git clone https://github.com/RusianHu/svg-converter-tools-mcp.git
cd svg_converter_tools_mcp
# 基础安装
pip install . -i https://pypi.tuna.tsinghua.edu.cn/simple/
# 开发模式安装
pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple/
安装可选依赖（强烈推荐）
# 安装 Cairo C库 支持（最高质量渲染）
pip install .[cairo] -i https://pypi.tuna.tsinghua.edu.cn/simple/
# 安装 SVGLib 支持（良好兼容性）
pip install .[svglib] -i https://pypi.tuna.tsinghua.edu.cn/simple/
# 安装所有可选依赖（推荐）
pip install .[full] -i https://pypi.tuna.tsinghua.edu.cn/simple/
# 开发环境安装
pip install .[dev] -i https://pypi.tuna.tsinghua.edu.cn/simple/
Cairo C库 安装说明
为了获得最佳的 SVG 渲染质量，建议安装 Cairo C库：
Windows 用户：
- 访问 GTK for Windows Runtime Environment
- 下载并安装最新版本的 GTK+ Runtime Environment
- 然后安装 cairosvg：
pip install cairosvg -i https://pypi.tuna.tsinghua.edu.cn/simple/
Linux/macOS 用户：
# Ubuntu/Debian
sudo apt-get install libcairo2-dev libgirepository1.0-dev
# CentOS/RHEL
sudo yum install cairo-devel gobject-introspection-devel
# macOS
brew install cairo gobject-introspection
# 然后安装 cairosvg
pip install cairosvg -i https://pypi.tuna.tsinghua.edu.cn/simple/
验证安装
# 检查版本信息
python -m svg_converter_mcp --version
# 检查依赖项状态
python -m svg_converter_mcp --check-deps
🔌 MCP 客户端配置
基本配置
在您的 MCP 客户端配置文件（如 mcp_settings.json）中添加：
{
"mcpServers": {
"svg-converter-mcp": {
"command": "python",
"args": ["-m", "svg_converter_mcp"],
"disabled": false
}
}
}
🛠️ 可用工具函数
安装后，MCP 客户端可以使用以下 6 个工具函数：
1. convert_svg_file
从文件路径转换 SVG
- 参数:
svg_file_path,output_file_path,output_format,width,height,scale,quality,background,transparent,prefer_engine - 返回: 转换结果信息，包含输出路径、文件大小、使用的引擎等
- 用途: 转换本地 SVG 文件为指定格式
2. convert_svg_string
从 SVG 字符串内容转换
- 参数:
svg_content,output_file_path,output_format,width,height,scale,quality,background,transparent,prefer_engine - 返回: 转换结果信息
- 用途: 直接从内存中的 SVG 内容转换，无需先保存为文件
3. batch_convert_svg_files
批量转换多个 SVG 文件
- 参数:
svg_files,output_directory,output_format,width,height,quality,background,transparent,prefer_engine - 返回: 批量转换结果报告，包含成功/失败统计
- 用途: 一次性处理多个 SVG 文件，提高效率
4. get_converter_engine_info
获取转换引擎信息
- 参数:
prefer_engine - 返回: 当前引擎状态、可用引擎列表、安装建议
- 用途: 查看系统中可用的转换引擎状态
5. get_svg_file_info
获取 SVG 文件详细信息
- 参数:
svg_file_path - 返回: 文件信息、尺寸分析、转换建议
- 用途: 分析 SVG 文件的特征和复杂度
6. get_svg_string_info
获取 SVG 字符串信息
- 参数:
svg_content - 返回: 内容分析、特征检测、转换建议
- 用途: 分析 SVG 内容特征，如是否包含中文字符等
⚙️ 转换引擎说明
🏆 Cairo C库 (cairosvg) - 推荐
- ✅ 最高质量: 完整的 SVG 规范支持
- ✅ 中文优化: 优秀的中文字体渲染效果
- ✅ 功能完整: 支持复杂的 SVG 特性
- ❌ 依赖要求: 需要额外安装 Cairo 库
pip install cairosvg -i https://pypi.tuna.tsinghua.edu.cn/simple/
🥈 SVGLib (svglib + reportlab) - 兼容
- ✅ 纯 Python: 无需系统级依赖
- ✅ 良好支持: 支持大部分 SVG 特性
- ⚠️ 中文限制: 中文字体支持有限
- ✅ 稳定性: 成熟的 Python 实现
pip install svglib reportlab -i https://pypi.tuna.tsinghua.edu.cn/simple/
🥉 PIL (Pillow) - 后备
- ✅ 内置支持: 无需额外依赖
- ✅ 轻量级: 占用资源少
- ❌ 功能限制: 仅支持基本 SVG 元素
- ❌ 质量一般: 中文字体渲染效果有限
🔧 配置选项
命令行参数
| 参数 | 说明 | 默认值 | 示例 |
|---|---|---|---|
--transport | 传输协议 | stdio | http, sse |
--host | 服务器地址 | 127.0.0.1 | 0.0.0.0 |
--port | 端口号 | 8000 | 9000 |
--debug | 调试模式 | False | - |
--version | 显示版本 | - | - |
--check-deps | 检查依赖 | - | - |
转换参数
| 参数 | 类型 | 说明 | 范围/选项 |
|---|---|---|---|
output_format | str | 输出格式 | png, ico, jpg, jpeg |
width | int | 输出宽度 | 1-8192 像素 |
height | int | 输出高度 | 1-8192 像素 |
scale | float | 缩放比例 | 0.1-10.0 |
quality | int | JPG 质量 | 1-100 |
background | str | 背景颜色 | 颜色名称或十六进制 |
transparent | bool | 透明背景 | true, false |
prefer_engine | str | 首选引擎 | auto, cairosvg, svglib, pil |
🐛 故障排除
常见问题
1. 导入错误
ImportError: No module named 'svg_converter_mcp'
解决方案:
# 确保包已正确安装
pip install -e .
# 或重新安装
pip uninstall svg-converter-mcp -y && pip install .
2. 依赖库缺失
DependencyError: cairosvg 和 svglib 均未安装
解决方案:
# 安装推荐的依赖库
pip install .[full] -i https://pypi.tuna.tsinghua.edu.cn/simple/
3. 中文字符显示异常
现象: 中文字符显示为方块或乱码
解决方案:
- 确保安装了 cairosvg:
pip install cairosvg - 检查系统中文字体: 确保系统安装了中文字体
- 使用引擎检查:
python -m svg_converter_mcp --check-deps
4. MCP 客户端连接失败
现象: MCP 客户端无法连接到服务
解决方案:
- 检查 Python 路径是否正确
- 确认包已正确安装:
python -m svg_converter_mcp --version - 验证配置文件语法: 确保 JSON 格式正确
- 检查端口占用: 如使用 HTTP 模式，确保端口未被占用
5. 转换质量不佳
现象: 输出图像质量不理想
解决方案:
- 优先使用 cairosvg 引擎
- 适当增加输出尺寸 (
width,height) - 对于文本内容，建议使用 PNG 格式
- 检查原始 SVG 文件质量
性能优化建议
- 安装 Cairo C库: 获得最佳转换质量和性能
- 使用批量转换: 处理多个文件时使用
batch_convert_svg_files - 合理设置尺寸: 避免过大的输出尺寸影响性能
- 选择合适格式: PNG 用于图标，JPG 用于照片
- 缓存结果: 对于重复转换，考虑缓存输出结果
核心组件关系
classDiagram
class SVGConverter {
+prefer_engine: str
+engine: str
+convert_file(svg_path, output_path, ...)
+convert_string(svg_content, output_path, ...)
+batch_convert(svg_files, output_dir, ...)
+get_svg_info(svg_path)
+get_engine_info()
-_check_dependencies()
-_select_engine()
-_render_svg_with_hybrid_method()
-_convert_with_cairosvg()
-_convert_with_svglib()
}
class FastMCP {
+name: str
+instructions: str
+run(transport, host, port)
}
class ConverterTools {
+convert_svg_file()
+convert_svg_string()
+batch_convert_svg_files()
+get_converter_engine_info()
+get_svg_file_info()
+get_svg_string_info()
}
class Engines {
<<interface>>
+Cairo C库
+SVGLib + ReportLab
+PIL (Pillow)
+混合渲染引擎
}
class Exceptions {
+SVGConverterError
+DependencyError
+ConversionError
}
FastMCP --> ConverterTools : 注册工具函数
ConverterTools --> SVGConverter : 使用
SVGConverter --> Engines : 调用
SVGConverter --> Exceptions : 抛出
note for SVGConverter "核心转换类\n支持多种引擎\n智能中文渲染"
note for FastMCP "MCP 服务框架\n支持多种传输协议"
note for Engines "转换引擎优先级:\n1. Cairo (最高质量)\n2. SVGLib (良好兼容)\n3. PIL (基本功能)"
🙏 致谢
📄 许可证
本项目采用 MIT 许可证。
Related Servers
Jira MCP Server
A server for integrating Jira with Claude, enabling project and issue management. Requires configuration via environment variables.
Mautic
Integrates with the Mautic marketing automation platform.
StashDog MCP Server
A server providing natural language tools to manage your StashDog inventory.
Draw.io
Integrates Draw.io's diagramming capabilities with AI agents, enabling programmatic diagram control and analysis.
Israel statistics mcp
MCP server that provides programmatic access to the Israeli Central Bureau of Statistics (CBS) price indices and economic data
Time MCP Server
Provides current time information and timezone conversion capabilities.
Freee MCP Scalar
AI-driven integration with the freee accounting service via the Model Context Protocol.
Invoice MCP
Create professional PDF invoices using natural language.
Standard Metrics MCP Server
Connects to the Standard Metrics API to enable AI-powered analysis of venture capital portfolio data.
OneNote MCP
An MCP server for Microsoft OneNote that supports personal notebooks and caches credentials for authentication.