Pic2svg MCP server and Node client

Turn a local raster image into SVG filled paths through the Pic2svg HTTP API. This repository contains a dependency-free Node client, command-line tool and stdio Model Context Protocol server. It is useful for tracing logos, icons and flat illustrations in scripts or agent workflows.

The client runs locally; tracing runs on Pic2svg's server. Your input image is uploaded. This is deterministic vector tracing, not generative image creation, an offline tracer or a hosted-service source release. Output is SVG, not centerline cutting instructions or a guarantee of machine-ready geometry.

Install from source

Requirements: Node.js 20 or later and Git, or download this repository's ZIP. No dependency installation is needed. Tests and live conversion were checked with Node 24.22.1; Node 20 is the declared minimum, not a separately tested runtime in this release.

git clone https://github.com/szj2ys/pic2svg-mcp.git
cd pic2svg-mcp
node --test
node ./pic2svg-mcp.mjs trace ./logo.png --preset compact --out ./logo-traced.svg

Replace ./logo.png with your own image. The npm registry returned 404 for pic2svg-mcp on 2026-10-27. Use this source installation; npx pic2svg-mcp is not a verified installation path.

Without --out, the CLI writes <input-name>.pic2svg.svg beside the input. An existing output file is overwritten, including an explicitly selected output path. Choose a new destination and keep it different from your input. The client reads the complete image into memory and has no explicit request timeout.

Related MCP server: image2svg-mcp

Use with an MCP client

Add a stdio server using the absolute path to the downloaded source. Configuration file location and reload behavior depend on your MCP client.

{
  "mcpServers": {
    "pic2svg": {
      "command": "node",
      "args": ["/absolute/path/to/pic2svg-mcp/pic2svg-mcp.mjs"]
    }
  }
}

On Windows, use escaped backslashes or forward slashes in the JSON path. If your MCP host cannot resolve node, supply its absolute executable path.

The trace_image_to_svg tool accepts:

The server implements newline-delimited JSON-RPC over stdio, initialization, tool discovery and tool calls. The included tests exercise those behaviors against a local fixture server; they do not certify every third-party MCP application. Tell the image owner that the image will leave the machine before uploading private material.

Use from Node

import { imageFromPath, trace } from './client.mjs';
import { writeFile } from 'node:fs/promises';

const input = await imageFromPath('./logo.png');
const result = await trace({ ...input, preset: 'compact' });
await writeFile('./logo-traced.svg', result.svgText);
console.log(result.canvas, result.sizeKB, result.remaining);

Public HTTP API

Authentication: no API key or account is required for this endpoint. Use HTTPS:

POST https://api.pic2svg.com/api/v1/trace
Content-Type: application/json

Request fields:

{
  "imageBase64": "data:image/png;base64,<your-image-bytes>",
  "fileName": "logo.png",
  "preset": "balanced"
}

imageBase64 is required and accepts a data URL or raw base64. fileName and preset are optional. The accepted preset names are balanced, compact and sharp. PNG, JPG, WebP, GIF, BMP and TIFF inputs are supported. Large traces are reduced to approximately 600,000 pixels; transparent areas become white background shapes.

A successful response is JSON with svgText (SVG markup), mode (trace mode), canvas (w, h, paths) and sizeKB. The Node client additionally exposes remaining from X-RateLimit-Remaining, or null if the header is absent. The API provides SVG only; the website's other export formats and plans are separate.

The service has a free daily allowance. Source defaults are 50 traces per client and 500 globally per UTC day; deployment configuration can change these and availability is not guaranteed. Observe the response headers X-RateLimit-Limit and X-RateLimit-Remaining where present. Quotas are best-effort process-memory counters and may reset on restart. A refused conversion may still consume allowance.

CORS: an OPTIONS preflight on 2026-10-27 from https://example.com, requesting POST with content-type, returned 200 without Access-Control-Allow-* headers. That origin did not receive permission for a direct browser JSON request. Use Node/server/CLI requests; do not assume arbitrary browser cross-origin access. This observation does not establish behavior for every origin.

PIC2SVG_API_URL optionally changes the receiving API base URL. Set it only when you intend to send the image to another compatible deployment. No API key is added by this client.

Privacy and limitations

Images are sent to the selected remote API, not processed offline. The normal Pic2svg trace implementation uses its own vector-tracing engine rather than a third-party generative AI service. This repository makes no additional image-retention guarantee; consult the service's privacy policy before sensitive uploads.

Filled paths can overlap and are not centerlines. Inspect the output in your design or cutting software. The SVG cut-file checker can help inspect SVG structure before further manual preparation.

Development and license

node --test runs the client and stdio/CLI tests with a local fixture API. It does not send test images to production. node scripts/check-release.mjs checks npm packaging metadata with a dry run; a passing check is not proof that a package has been published.

The client code is under the MIT license, preserving the existing copyright notice. The hosted Pic2svg service and its backend are separate; this license does not grant rights to that service's private implementation or override its terms.