glassypic-mcp-server

# @glassypic/mcp-server

[![npm version](https://img.shields.io/npm/v/@glassypic/mcp-server.svg)](https://www.npmjs.com/package/@glassypic/mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-Compatible-brightgreen.svg)](https://modelcontextprotocol.io)

MCP server for [GlassyPic](https://glassypic.com). One tool that turns raw images into production-ready assets. Support upscaling, resizing/cropping, compression, file format conversion, and SEO filename & alt text generation. Just describe the outcome you want in natrual language.

## Quick Start

Add to your MCP client config:

```json
{
  "mcpServers": {
    "glassypic": {
      "command": "npx",
      "args": ["-y", "@glassypic/mcp-server@latest"]
    }
  }
}
```

No signup required. Works out of the box with 20 free daily credits.

> **Windows users:** If the server doesn't appear after editing a JSON config, your client likely can't resolve `npx` from PATH (a common, silent failure). Wrap the command with `cmd /c`:
>
> ```json
> {
>   "mcpServers": {
>     "glassypic": {
>       "command": "cmd",
>       "args": ["/c", "npx", "-y", "@glassypic/mcp-server@latest"]
>     }
>   }
> }
> ```
>
> This applies to the hand-edited JSON configs below (Claude Desktop, Cursor, Windsurf, Cline). The CLI commands (Claude Code, Gemini CLI, Codex CLI) are unaffected.

### Client-Specific Setup

<details>
<summary><strong>Claude Desktop</strong></summary>

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "glassypic": {
      "command": "npx",
      "args": ["-y", "@glassypic/mcp-server@latest"]
    }
  }
}
```
</details>

<details>
<summary><strong>Claude Code</strong></summary>

```bash
claude mcp add glassypic -- npx -y @glassypic/mcp-server@latest
```
</details>

<details>
<summary><strong>Cursor</strong></summary>

Add to `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "glassypic": {
      "command": "npx",
      "args": ["-y", "@glassypic/mcp-server@latest"]
    }
  }
}
```
</details>

<details>
<summary><strong>Windsurf</strong></summary>

Edit `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "glassypic": {
      "command": "npx",
      "args": ["-y", "@glassypic/mcp-server@latest"]
    }
  }
}
```
</details>

<details>
<summary><strong>Smithery</strong></summary>
Install via Smithery: [![smithery badge](https://smithery.ai/badge/glassypic/mcp-server)](https://smithery.ai/servers/glassypic/mcp-server)
</details>

<details>
<summary><strong>Cline</strong></summary>

Open Cline settings → MCP Servers → Add, then paste:

```json
{
  "mcpServers": {
    "glassypic": {
      "command": "npx",
      "args": ["-y", "@glassypic/mcp-server@latest"]
    }
  }
}
```
</details>

<details>
<summary><strong>Gemini CLI</strong></summary>

```bash
gemini mcp add --transport stdio glassypic npx -y @glassypic/mcp-server@latest
```

Or edit `~/.gemini/settings.json` (global) or `.gemini/settings.json` in your project root:

```json
{
  "mcpServers": {
    "glassypic": {
      "command": "npx",
      "args": ["-y", "@glassypic/mcp-server@latest"]
    }
  }
}
```

Verify it's running inside Gemini CLI with `/mcp list`.
</details>

<details>
<summary><strong>OpenAI Codex CLI</strong></summary>

```bash
codex mcp add glassypic -- npx -y @glassypic/mcp-server@latest
```

Or edit `~/.codex/config.toml` manually:

```toml
[mcp_servers.glassypic]
command = "npx"
args = ["-y", "@glassypic/mcp-server@latest"]
```
</details>

## Tool: `optimize_image`

One tool that turns raw images into production-ready assets using AI-powered algorithm and multi-step agents (typically 60-80% size reduction), with optional resize, upscale, format conversion, and SEO metadata generation. Supports JPEG, PNG, WebP, HEIC, GIF, AVIF, TIFF, and BMP. Accepts absolute local file paths or remote URLs.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `input` | string | Yes | — | Absolute local file path or remote URL |
| `output_path` | string | No | auto | File path or directory (ending in `/`). If omitted: saves next to original with SEO slug or `.glassypic` suffix |
| `output_format` | string | No | original | `jpg`, `png`, `webp`, `avif`, `gif`, or `original` |
| `output_width_px` | int | No | — | Target width in pixels |
| `output_height_px` | int | No | — | Target height in pixels |
| `output_upscale_factor` | int | No | — | AI upscale factor: `2` (2×) or `4` (4×) |
| `output_resize_behavior` | string | No | pad | `pad` (white padding) or `crop` (smart crop). Only used when both width and height are set |
| `output_seo_tag_gen` | bool | No | true | Generate SEO metadata and rename file to SEO slug. Costs 1 extra credit |
| `output_file_size_limit` | int | No | — | Target maximum output file size in bytes. Server attempts to meet this via additional compression. Not guaranteed |
| `gif_frame_limit` | int | No | 100 | Max frames to process for animated GIFs (1–100). Reduces credit cost by sampling fewer frames |
| `confirm_gif_cost` | bool | No | — | Set to `true` to proceed after reviewing the animated GIF cost warning. Required for animated GIFs |

### Resize Behavior

| Dimensions provided | Behavior | `output_resize_behavior` |
|---|---|---|
| Width only | Proportional scale | N/A |
| Height only | Proportional scale | N/A |
| Width + Height | Exact dimensions, white padding | `pad` (default) |
| Width + Height | Exact dimensions, smart crop | `crop` |

### Examples

**Basic compression** — just compress, keep format and dimensions:

```json
{ "input": "/Users/me/photos/hero.png" }
```

**Convert to WebP:**

```json
{ "input": "/Users/me/hero.png", "output_format": "webp" }
```

**Resize proportionally** — set one dimension, the other scales:

```json
{ "input": "/Users/me/hero.png", "output_width_px": 1200 }
```

**Exact dimensions with padding** — white bars fill the gap:

```json
{ "input": "/Users/me/hero.png", "output_width_px": 1080, "output_height_px": 1080 }
```

**Exact dimensions with smart crop:**

```json
{ "input": "/Users/me/hero.png", "output_width_px": 1080, "output_height_px": 1080, "output_resize_behavior": "crop" }
```

**AI upscale 4x:**

```json
{ "input": "/Users/me/icon.png", "output_upscale_factor": 4 }
```

**From URL, save to directory:**

```json
{ "input": "https://example.com/photo.jpg", "output_path": "/Users/me/assets/" }
```

**Skip SEO to save 1 credit:**

```json
{ "input": "/Users/me/hero.png", "output_seo_tag_gen": false }
```

### Output

Returns a text summary and structured metadata:

```
Optimized: /Users/me/photos/modern-office-workspace.webp
Size: 142.3 KB
Compression: 73%
Format: webp
Dimensions: 1920x1080
Alt text: Modern office workspace with laptop and coffee cup on wooden desk
```

**Structured output fields:**

```json
{
  "output_path": "/Users/me/photos/modern-office-workspace.webp",
  "output_size_bytes": 145715,
  "output_width_px": 1920,
  "output_height_px": 1080,
  "output_format": "webp",
  "compression_ratio": 0.27,
  "seo_alt_text": "Modern office workspace with laptop and coffee cup on wooden desk",
  "seo_keywords": ["office", "workspace", "laptop", "desk", "modern"],
  "seo_filename": "modern-office-workspace"
}
```

## Supported Formats

| Format | Input | Output | Notes |
|--------|-------|--------|-------|
| JPG | Yes | Yes | |
| PNG | Yes | Yes | |
| WebP | Yes | Yes | |
| AVIF | Yes | Yes | |
| GIF | Yes | Yes | Animated GIFs preserved when output is GIF |
| SVG | Yes | Yes | SVG→SVG optimized via SVGO; raster↔SVG conversion supported |
| ICO | Yes | Yes | Smart rebuild: generates 16, 24, 32, 48, 256px favicon set |
| HEIC/HEIF | Yes* | No | Auto-converted to JPG at upload |
| TIFF | Yes* | No | Auto-converted to JPG at upload |
| BMP | Yes* | No | Auto-converted to JPG at upload |

GlassyPic supports high-quality conversion between any input and output format combination.
Converting an animated GIF to a non-GIF format (JPG, PNG, WebP, AVIF) preserves only the first frame.
Converting an animated GIF to a GIF format supports upscaling/resizing while preserving the animation and quality. You may also reduce animated GIF file size by decreasing the number of output frames.

Max upload file size: 50 MB.

### SVG & ICO Examples

```
# Optimize an SVG file (keeps as vector)
Optimize logo.svg and keep it as SVG

# Convert SVG to raster
Convert icon.svg to a 512x512 PNG

# Trace raster to vector SVG
Convert my logo.png to a vector SVG

# Generate favicon set from any image
Convert logo.png to an ICO favicon

# Generate single-size ICO
Convert logo.png to a 32x32 ICO

# Extract largest icon from ICO
Convert favicon.ico to PNG
```

## How It Works

```
Local file or URL
  → Upload to GlassyPic API
    → Smart compression (lossy, typically 60-80% reduction)
    → AI SEO tag generation (alt text, keywords, filename)
    → Optional: resize, upscale, format conversion
  → Download optimized file
    → Save with SEO filename slug (or .glassypic suffix if SEO disabled)
```

All processing happens server-side via the [GlassyPic API](https://api.glassypic.com). The MCP server is a thin client that orchestrates the pipeline.

## Credits

| | Guest | Free | Pro | Max |
|---|---|---|---|---|
| Credits/day or month | 20/day | 50/day | 3,000/month | 10,000/month |
| Images/day (default settings) | ~5 | ~12 | ~750 | ~2,500 |
| Cost per image | 3 credits + 1 SEO | same | same | same |
| Signup required | No | Free signup | Paid | Paid |

Session data is stored locally at `~/.glassypic/session.json` and persists across invocations. 

## Account & Credits

Log in to unlock more credits and share them across the web app and MCP server:

```
Use the login tool to sign in.
Use the status tool to check your current credits.