MCP SVG Converter

English | 中文

<a name="english"></a>

English

A Model Context Protocol (MCP) server that provides tools for converting SVG code to high-quality PNG and JPG images with detailed customization options.

Features

• Convert SVG code to high-quality PNG images with transparency support
• Convert SVG code to high-quality JPG images with customizable quality settings
• Automatic dimension detection and preservation from original SVG
• Support for scaling to higher resolutions
• Background color customization
• Intelligent path handling with automatic redirection to allowed directories
• Secure file system access with configurable permissions

Installation

Quick Install with npx

npx mcp-svg-converter /path/to/allowed/directory

Global Installation

npm install -g mcp-svg-converter
mcp-svg-converter /path/to/allowed/directory

From Source

Prerequisites

• Node.js 16 or higher
• npm or yarn

Installation Steps

1. Clone this repository

   git clone https://github.com/surferdot/mcp-svg-converter.git
   cd mcp-svg-converter
   

2. Install dependencies

   npm install
   

3. Build the project

   npm run build
   

Usage

As a standalone server

Run the server by specifying one or more allowed directories where the converted images can be saved:

node build/index.js /path/to/allowed/directory1 /path/to/allowed/directory2

With Claude Desktop

1. Download and install Claude Desktop

2. Create or confirm you have access to an output directory:

   # macOS/Linux
   mkdir -p ~/Desktop/svg-output
   
   # Windows
   mkdir "%USERPROFILE%\Desktop\svg-output"
   

3. Configure Claude Desktop by editing the configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

4. Open the Claude app, click on the Claude menu in your system menu bar and select "Settings..."

5. Click on "Developer" in the left sidebar

6. Click "Edit Config" to open the configuration file

7. Add this server configuration:

Using npm package with npx (recommended)

{
  "mcpServers": {
    "svg-converter": {
      "command": "npx",
      "args": [
        "mcp-svg-converter",
        "/absolute/path/to/output/directory"
      ]
    }
  }
}

Using global installation

If you've installed the package globally:

{
  "mcpServers": {
    "svg-converter": {
      "command": "mcp-svg-converter",
      "args": [
        "/absolute/path/to/output/directory"
      ]
    }
  }
}

Using local build

If you've built from source:

{
  "mcpServers": {
    "svg-converter": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-svg-converter/build/index.js",
        "/absolute/path/to/output/directory"
      ]
    }
  }
}

1. Save the file and restart Claude Desktop

Verifying the Setup

When Claude Desktop restarts, if configured correctly:

1. You should see a hammer icon <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-hammer-icon.svg" style="display: inline; height: 1.3em; vertical-align: middle"> at the bottom right of the input box indicating MCP tools are available.
2. Clicking the hammer icon should show the svg-to-png and svg-to-jpg tools.

Examples in Claude Desktop

Example 1: Converting a Simple SVG to PNG

In Claude Desktop, send a message like:

Please convert this SVG to PNG and save it to my output directory:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 100" width="200" height="100">
  <rect x="10" y="10" width="80" height="80" fill="#4285f4" />
  <circle cx="140" cy="50" r="40" fill="#ea4335" />
  <path d="M10 50 L90 50 L50 90 Z" fill="#fbbc05" />
  <text x="100" y="20" font-family="Arial" font-size="12" text-anchor="middle" fill="#34a853">SVG Example</text>
</svg>

Example 2: High-Quality JPG Conversion

Please convert this SVG to a JPG with 95% quality and 2x scaling:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 200">
  <rect width="200" height="200" fill="#f0f0f0" />
  <circle cx="100" cy="100" r="80" fill="#ff6b6b" />
  <path d="M100 50 L130 150 L70 150 Z" fill="white" />
</svg>

Tools

svg-to-png

Converts SVG code to a high-quality PNG image with transparency support.

Parameters:

• svgCode (string, required): The SVG code to convert
• outputPath (string, required): Path where the PNG file should be saved
• backgroundColor (string, optional): Background color (default: transparent)
• scale (number, optional): Scale factor for higher resolution (default: 1)

svg-to-jpg

Converts SVG code to a high-quality JPG image.

Parameters:

• svgCode (string, required): The SVG code to convert
• outputPath (string, required): Path where the JPG file should be saved
• backgroundColor (string, optional): Background color (default: white)
• quality (number, optional): JPEG quality from 1-100 (default: 90)
• scale (number, optional): Scale factor for higher resolution (default: 1)

Advanced Usage Tips

Specifying Multiple Output Directories

You can specify multiple allowed output directories for more flexible file saving:

{
  "mcpServers": {
    "svg-converter": {
      "command": "npx",
      "args": [
        "mcp-svg-converter",
        "/Users/yourusername/Desktop/svg-output",
        "/Users/yourusername/Documents/svg-images",
        "/Users/yourusername/Downloads"
      ]
    }
  }
}

Using Custom Output Filenames

Specify detailed file paths in your request:

Please convert this SVG to PNG, and save it as "colorful_shapes.png" in my output directory.

<svg>...</svg>

Automatic Path Redirection

If you request saving to a non-allowed directory, the converter automatically redirects to an allowed directory and informs you of the actual save location.

Troubleshooting

Claude Doesn't Show MCP Tools Icon

1. Verify the configuration file has correct JSON syntax
2. Ensure all paths are absolute paths
3. Make sure output directories exist and are writable
4. Completely exit and restart Claude Desktop
5. Check Claude logs:
   • macOS: ~/Library/Logs/Claude/mcp*.log
   • Windows: %APPDATA%\Claude\logs\mcp*.log

Tool Execution Fails

1. Ensure mcp-svg-converter is correctly installed
2. Check output directory permissions
3. Verify the SVG code is valid
4. Check Claude logs for detailed error messages

"Command Not Found" Error

1. Ensure mcp-svg-converter is globally installed or correctly reference npx
2. Confirm npm's global bin directory is in your PATH
3. Try using full paths in configuration

Debugging

You can use the MCP Inspector to debug and test the server directly:

npx @modelcontextprotocol/inspector npx mcp-svg-converter /path/to/allowed/directory

This opens an interactive interface where you can test all available tools without going through Claude Desktop.

Security Considerations

• The server will only write files to the directories specified when starting the server
• If a user attempts to save to a non-allowed directory, the file will be automatically redirected to an allowed directory
• Path traversal attacks are prevented by proper path validation

License

MIT

---

<a name="中文"></a>

中文

MCP SVG 转换器是一个基于模型上下文协议 (MCP) 的服务器，提供将 SVG 代码转换为高质量 PNG 和 JPG 图像的工具，支持详细的自定义选项。

特点

• 将 SVG 代码转换为支持透明度的高质量 PNG 图像
• 将 SVG 代码转换为可定制质量设置的高质量 JPG 图像
• 自动检测并保留原始 SVG 的尺寸
• 支持缩放到更高分辨率
• 可自定义背景颜色
• 智能路径处理，自动重定向到允许的目录
• 可配置权限的安全文件系统访问

安装

使用 npx 快速安装

npx mcp-svg-converter /path/to/allowed/directory

全局安装

npm install -g mcp-svg-converter
mcp-svg-converter /path/to/allowed/directory

从源代码安装

前提条件

• Node.js 16 或更高版本
• npm 或 yarn

安装步骤

1. 克隆此仓库

   git clone https://github.com/surferdot/mcp-svg-converter.git
   cd mcp-svg-converter
   

2. 安装依赖

   npm install
   

3. 构建项目

   npm run build
   

使用方法

作为独立服务器运行

通过指定一个或多个允许存储转换后图像的目录来运行服务器：

node build/index.js /path/to/allowed/directory1 /path/to/allowed/directory2

与 Claude Desktop 一起使用

1. 下载并安装 Claude Desktop

2. 创建或确认你有权限访问的输出目录：

   # macOS/Linux
   mkdir -p ~/Desktop/svg-output
   
   # Windows
   mkdir "%USERPROFILE%\Desktop\svg-output"
   

3. 配置 Claude Desktop：

   • 打开 Claude 应用程序
   • 点击系统菜单栏中的 Claude 图标
   • 选择"Settings..."（设置）
   • 在左侧菜单中选择"Developer"（开发者）
   • 点击"Edit Config"（编辑配置）按钮

4. 编辑配置文件：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

5. 添加服务器配置：

使用 npm 包与 npx（推荐）

{
  "mcpServers": {
    "svg-converter": {
      "command": "npx",
      "args": [
        "mcp-svg-converter",
        "/absolute/path/to/output/directory"
      ]
    }
  }
}

使用全局安装

如果你已全局安装了此包：

{
  "mcpServers": {
    "svg-converter": {
      "command": "mcp-svg-converter",
      "args": [
        "/absolute/path/to/output/directory"
      ]
    }
  }
}

使用本地构建

如果你从源代码构建：

{
  "mcpServers": {
    "svg-converter": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-svg-converter/build/index.js",
        "/absolute/path/to/output/directory"
      ]
    }
  }
}

1. 保存文件并重启 Claude Desktop

验证设置

当 Claude Desktop 重启后，如果配置正确：

1. 你应该在输入框

---