SVGMaker MCP Server

1# SVGMaker MCP Server
2A powerful MCP server for generating, editing, and converting SVG images using SVGMaker API.
3 
4[![Website](https://img.shields.io/badge/Website-SVGMaker.io-blue)](https://svgmaker.io)
5[![npm version](https://img.shields.io/npm/v/@genwave/svgmaker-mcp.svg)](https://www.npmjs.com/package/@genwave/svgmaker-mcp)
6[![License](https://img.shields.io/npm/l/@genwave/svgmaker-mcp.svg)](https://github.com/GenWaveLLC/svgmaker-mcp/blob/main/LICENSE)
7[![Build Status](https://img.shields.io/github/actions/workflow/status/GenWaveLLC/svgmaker-mcp/ci.yml?branch=main)](https://github.com/GenWaveLLC/svgmaker-mcp/actions)
8[![npm downloads](https://img.shields.io/npm/dm/@genwave/svgmaker-mcp.svg)](https://www.npmjs.com/package/@genwave/svgmaker-mcp)
9 
10## 🎨 MCP Server in Action
11 
12![MCP Capabilities Demo](docs/mcp-capabilities-demo.svg)
13 
14*This very illustration came to life through our own SVGMaker MCP server—a living example of AI assistants and vector graphics working in perfect harmony via the Model Context Protocol.*
15 
16## 🌟 Highlights
17 
18- **🎨 AI-Powered SVG Generation**: Create SVGs from text descriptions
19- **✏️ Smart SVG Editing**: Edit existing SVGs with natural language
20- **🔄 Image-to-SVG Conversion**: Convert any image to scalable SVG
21- **🔒 Secure File Operations**: Built-in path validation and security
22- **⚡ Real-Time Progress**: Live updates during operations
23- **📝 Type Safety**: Full TypeScript support with type definitions
24 
25## 📋 Table of Contents
26 
27- [Requirements](#-requirements)
28- [Installation](#-installation)
29- [Quick Start](#-quick-start)
30- [LLM Integrations](#-llm-integrations)
31- [Available Tools](#️-available-tools)
32- [Configuration](#️-configuration)
33- [Development](#-development)
34- [Contributing](#-contributing)
35 
36## 💻 Requirements
37 
38- Node.js: Minimum version 18.0.0
39  ```bash
40  node --version  # Should be >= v18.0.0
41  ```
42- npm: Minimum version 7.0.0
43  ```bash
44  npm --version   # Should be >= 7.0.0
45  ```
46- Operating Systems: 
47  - Linux (Ubuntu 20.04+, CentOS 8+)
48  - macOS (10.15+)
49  - Windows (10+)
50- SVGMaker API key ([Get one here](https://svgmaker.io/account))
51 
52## 📦 Package Structure
53 
54```
55@genwave/svgmaker-mcp/
56├── build/             # Compiled JavaScript files
57├── docs/              # Documentation
58│   └── api/           # API documentation
59├── src/               # Source TypeScript files
60│   ├── tools/         # MCP tool implementations
61│   ├── services/      # API integration
62│   └── utils/         # Utility functions
63└── types/             # TypeScript declarations
64```
65 
66## 🚀 Installation
67 
68```bash
69# Using npm
70npm install @genwave/svgmaker-mcp
71 
72# Using yarn
73yarn add @genwave/svgmaker-mcp
74```
75 
76### Basic Setup
77 
781. Create .env file:
79```bash
80SVGMAKER_API_KEY="your_api_key_here"
81```
82 
832. Start the server:
84```bash
85npx svgmaker-mcp
86```
87 
88## 🔌 LLM Integrations
89 
90### 🔌 Claude Desktop
91 
921. Add to claude_desktop_config.json:
93```json
94{
95  "mcpServers": {
96    "svgmaker": {
97      "command": "npx",
98      "args": ["@genwave/svgmaker-mcp"],
99      "transport": "stdio",
100      "env": {
101        "SVGMAKER_API_KEY": "your_api_key_here"
102      }
103    }
104  }
105}
106```
107 
1082. Example Claude prompt:
109```
110Generate an SVG of a minimalist mountain landscape:
111<mcp>
112{
113  "server": "svgmaker",
114  "tool": "svgmaker_generate",
115  "arguments": {
116    "prompt": "Minimalist mountain landscape with sun",
117    "output_path": "./landscape.svg",
118    "quality": "high",
119    "aspectRatio": "landscape"
120  }
121}
122</mcp>
123```
124 
125### 🔌 Cursor
126 
127[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=svgmaker&config=eyJ0eXBlIjoibG9jYWwiLCJjb21tYW5kIjoibnB4IEBnZW53YXZlL3N2Z21ha2VyLW1jcCIsInRyYW5zcG9ydCI6InN0ZGlvIiwiZW52Ijp7IlNWR01BS0VSX0FQSV9LRVkiOiJ5b3VyX2FwaV9rZXlfaGVyZSJ9fQ%3D%3D)
128 
129 
130Or configure manually:
131 
1321. Configure in cursor settings:
133```json
134{
135  "mcpServers": {
136    "svgmaker": {
137      "type": "local",
138      "command": "npx",
139      "args": ["@genwave/svgmaker-mcp"],
140      "transport": "stdio",
141      "env": {
142        "SVGMAKER_API_KEY": "your_api_key_here"
143      }
144    }
145  }
146}
147```
148 
1492. Example usage in Cursor:
150```
151Use svgmaker to edit the logo.svg file and make it more modern:
152<mcp>
153{
154  "server": "svgmaker",
155  "tool": "svgmaker_edit",
156  "arguments": {
157    "input_path": "./logo.svg",
158    "prompt": "Make it more modern and minimalist",
159    "output_path": "./modern_logo.svg",
160    "quality": "high"
161  }
162}
163</mcp>
164```
165 
166### 🔌 Visual Studio Code
167 
168[<img alt="Install in VS Code (npx)" src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20SVGMaker%20MCP&color=0098FF">](https://insiders.vscode.dev/redirect/mcp/install?name=svgmaker&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%2C%22description%22%3A%22SVGMaker%20API%20Key%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40genwave%2Fsvgmaker-mcp%22%5D%2C%22env%22%3A%7B%22SVGMAKER_API_KEY%22%3A%22%24%7Binput%3AapiKey%7D%22%7D%7D)
169 
170 
171Or configure manually:
172 
1731. Configure in settings.json:
174```json
175{
176  "servers": {
177    "svgmaker": {
178      "type": "stdio",
179      "command": "npx",
180      "args": ["-y", "@genwave/svgmaker-mcp"],
181      "env": {
182        "SVGMAKER_API_KEY": "<your_api_key>"
183      }
184    }
185  }
186}
187```
188 
1892. Example usage in VS Code:
190```
191Generate a new icon for my app:
192<mcp>
193{
194  "server": "svgmaker",
195  "tool": "svgmaker_generate",
196  "arguments": {
197    "prompt": "Modern app icon with abstract geometric shapes",
198    "output_path": "./assets/icon.svg",
199    "quality": "high",
200    "aspectRatio": "square"
201  }
202}
203</mcp>
204```
205 
206### 🔌 WindSurf
207 
2081. Configure in settings:
209```json
210{
211  "mcpServers": {
212    "svgmaker": {
213      "command": "npx",
214      "args": ["-y", "@genwave/svgmaker-mcp"],
215      "env": {
216        "SVGMAKER_API_KEY": "<your_api_key>"
217      }
218    }
219  }
220}
221```
222 
2232. Example usage in WindSurf:
224```
225Convert the company logo to SVG:
226<mcp>
227{
228  "server": "svgmaker",
229  "tool": "svgmaker_convert",
230  "arguments": {
231    "input_path": "./branding/logo.png",
232    "output_path": "./branding/vector_logo.svg"
233  }
234}
235</mcp>
236```
237 
238### 🔌 Zed
239 
2401. Configure in settings:
241```json
242{
243  "context_servers": {
244    "svgmaker": {
245      "command": {
246        "path": "npx",
247        "args": ["-y", "@genwave/svgmaker-mcp"],
248        "env": {
249          "SVGMAKER_API_KEY": "<your_api_key>"
250        }
251      },
252      "settings": {}
253    }
254  }
255}
256```
257 
2582. Example usage in Zed:
259```
260Edit an existing SVG file:
261<mcp>
262{
263  "server": "svgmaker",
264  "tool": "svgmaker_edit",
265  "arguments": {
266    "input_path": "./diagrams/flowchart.svg",
267    "prompt": "Add rounded corners and smooth gradients",
268    "output_path": "./diagrams/enhanced_flowchart.svg",
269    "quality": "high"
270  }
271}
272</mcp>
273```
274 
275## 🛠️ Available Tools
276 
277### svgmaker_generate
278 
279Generate SVG images from text prompts. Supports style parameters for fine-grained control over the output.
280 
281```json
282{
283  "prompt": "A minimalist mountain landscape with sun",
284  "output_path": "/path/to/landscape.svg",
285  "quality": "medium",
286  "style": "flat",
287  "color_mode": "few_colors",
288  "composition": "full_scene",
289  "background": "transparent"
290}
291```
292 
293### svgmaker_edit
294 
295Edit existing SVGs or images with natural language. Supports the same style parameters as generate.
296 
297```json
298{
299  "input_path": "/path/to/input.svg",
300  "prompt": "Add a gradient background and make it more vibrant",
301  "output_path": "/path/to/enhanced.svg",
302  "quality": "high",
303  "style": "cartoon",
304  "background": "opaque"
305}
306```
307 
308### svgmaker_convert
309 
310Convert raster images to SVG using AI-powered vectorization.
311 
312```json
313{
314  "input_path": "/path/to/image.png",
315  "output_path": "/path/to/vector.svg"
316}
317```
318 
319## ⚙️ Configuration
320 
321### Environment Variables
322 
323| Variable | Description | Required | Default |
324|----------|-------------|----------|---------|
325| `SVGMAKER_API_KEY` | Your SVGMaker API key | ✅ Yes | - |
326| `SVGMMAKER_RATE_LIMIT_RPM` | API rate limit (requests per minute) | ❌ No | 2 |
327| `SVGMAKER_BASE_URL` | Custom SVGMaker API base URL | ❌ No | `https://api.svgmaker.io` |
328| `SVGMAKER_DEBUG` | Enable debug logging | ❌ No | `false` |
329 
330### Debug Logging
331 
332The server includes comprehensive logging for debugging and monitoring:
333 
334**Enable Logging:**
335```bash
336# Enable debug logging
337SVGMAKER_DEBUG=true npx @genwave/svgmaker-mcp
338 
339# Or set NODE_ENV to development
340NODE_ENV=development npx @genwave/svgmaker-mcp
341```
342 
343**Log Files Location:**
344- **macOS/Linux**: `~/.cache/svgmaker-mcp/logs/`
345- **Windows**: `%LOCALAPPDATA%/svgmaker-mcp/logs/`
346- **Fallback**: `./logs/` (in project directory)
347 
348**Log File Format:**
349```
350mcp-debug-2025-06-04T10-30-45-123Z.log
351```
352 
353## 🔍 Development
354 
355### Local Setup
356 
3571. Clone and install dependencies:
358```bash
359npm install
360```
361 
3622. Create .env file with your API key
363```bash
364SVGMAKER_API_KEY="your_api_key_here"
365```
366 
3673. Run in development mode:
368```bash
369npm run dev
370```
371 
372### Testing
373 
374Use the MCP Inspector for testing:
375```bash
376npx @modelcontextprotocol/inspector node build/index.js
377```
378 
379### CI/CD Workflow
380 
381This project uses GitHub Actions for continuous integration and deployment:
382 
3831. **Continuous Integration**
384   - Runs on every push to main branch and pull requests
385   - Performs linting, type checking, and building
386   - Ensures code quality and consistency
387 
3882. **Releasing a New Version**
389   - To release a patch version (bug fixes):
390     ```bash
391     npm run release:patch
392     ```
393   - To release a minor version (new features):
394     ```bash
395     npm run release:minor
396     ```
397   - To release a major version (breaking changes):
398     ```bash
399     npm run release:major
400     ```
401 
4023. **Publishing**
403   - Automatically publishes to npm when a new version tag is pushed
404 
405## 🔐 Security
406 
407- ✅ Path validation prevents directory traversal
408- ✅ Input sanitization for all parameters
409- ✅ Secure file operation handling
410- ✅ Environment variable protection
411- ✅ Rate limiting support
412 
413## 🤝 Contributing
414 
415We welcome contributions! Please see our [Contributing Guide](https://github.com/GenWaveLLC/svgmaker-mcp/blob/main/CONTRIBUTING.md) for details.
416 
417## ⭐ Features
418 
419### Input Format Support
420- SVG files (.svg)
421- PNG images (.png)
422- JPEG images (.jpg, .jpeg)
423- Other common image formats
424 
425### Output Capabilities
426- Clean, optimized SVG output
427- Multiple aspect ratio options
428- Background control (transparent/opaque)
429- High-quality vectorization
430 
431## 📝 License
432 
433MIT © [Genwave AI](https://genwave.xyz) - see the [LICENSE](https://github.com/GenWaveLLC/svgmaker-mcp/blob/main/LICENSE) file for details.
434