SVG Converter

一个基于 FastMCP 的专业 SVG 文件转换服务包，提供完整的 SVG 转换功能。支持将 SVG 转换为 PNG、ICO、JPG 等格式，优先使用 Cairo C库 进行高质量渲染，特别优化了中文字符的显示效果。

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

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 安装最新版本 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/

- 访问GTK for Windows Runtime Environment
- 下载并安装最新版本的 GTK+ Runtime Environment
- 然后安装 cairosvg：

pip install cairosvg -i https://pypi.tuna.tsinghua.edu.cn/simple/

# 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

{ "mcpServers": { "svg-converter-mcp": { "command": "python", "args": ["-m", "svg_converter_mcp"], "disabled": false } } }

- 参数:svg_file_path,output_file_path,output_format,width,height,scale,quality,background,transparent,prefer_engine
- 返回: 转换结果信息，包含输出路径、文件大小、使用的引擎等
- 用途: 转换本地 SVG 文件为指定格式

- 参数:svg_content,output_file_path,output_format,width,height,scale,quality,background,transparent,prefer_engine
- 返回: 转换结果信息
- 用途: 直接从内存中的 SVG 内容转换，无需先保存为文件

- 参数:svg_files,output_directory,output_format,width,height,quality,background,transparent,prefer_engine
- 返回: 批量转换结果报告，包含成功/失败统计
- 用途: 一次性处理多个 SVG 文件，提高效率

- 参数:prefer_engine
- 返回: 当前引擎状态、可用引擎列表、安装建议
- 用途: 查看系统中可用的转换引擎状态

- 参数:svg_file_path
- 返回: 文件信息、尺寸分析、转换建议
- 用途: 分析 SVG 文件的特征和复杂度

- 参数:svg_content
- 返回: 内容分析、特征检测、转换建议
- 用途: 分析 SVG 内容特征，如是否包含中文字符等

- ✅最高质量: 完整的 SVG 规范支持
- ✅中文优化: 优秀的中文字体渲染效果
- ✅功能完整: 支持复杂的 SVG 特性
- ❌依赖要求: 需要额外安装 Cairo 库

pip install cairosvg -i https://pypi.tuna.tsinghua.edu.cn/simple/

- ✅纯 Python: 无需系统级依赖
- ✅良好支持: 支持大部分 SVG 特性
- ⚠️中文限制: 中文字体支持有限
- ✅稳定性: 成熟的 Python 实现

pip install svglib reportlab -i https://pypi.tuna.tsinghua.edu.cn/simple/

- ✅内置支持: 无需额外依赖
- ✅轻量级: 占用资源少
- ❌功能限制: 仅支持基本 SVG 元素
- ❌质量一般: 中文字体渲染效果有限

ImportError: No module named 'svg_converter_mcp'

# 确保包已正确安装 pip install -e . # 或重新安装 pip uninstall svg-converter-mcp -y && pip install .

# 安装推荐的依赖库 pip install .[full] -i https://pypi.tuna.tsinghua.edu.cn/simple/

- 确保安装了 cairosvg:pip install cairosvg
- 检查系统中文字体: 确保系统安装了中文字体
- 使用引擎检查:python -m svg_converter_mcp --check-deps

- 检查 Python 路径是否正确
- 确认包已正确安装:python -m svg_converter_mcp --version
- 验证配置文件语法: 确保 JSON 格式正确
- 检查端口占用: 如使用 HTTP 模式，确保端口未被占用

- 优先使用 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 (基本功能)"

- FastMCP- 优秀的 MCP 服务框架
- CairoSVG- 高质量的 SVG 渲染库
- SVGLib- 纯 Python SVG 处理库
- Pillow- Python 图像处理库

MCP server for AI-powered SVG icon generation. Generate production-ready icons from text descriptions. Supports single icons, bundles, style customization, and regeneration.