@metalevel/snapix-mcp-server

MCP server for SnapiX - image optimization, conversion, AI generation, and gallery management via the Model Context Protocol. Get a free API key and start using it with your AI clients today, no credits required!

Built on @metalevel/snapix-sdk-core - the official typed TypeScript SDK for the SnapiX REST API.

Quick Start - Local (stdio)

Add to your AI client configuration:

VS Code (Copilot)

Add to .vscode/mcp.json:

{
  "inputs": [
    {
      "id": "SNAPIX_API_KEY",
      "type": "promptString",
      "description": "SnapiX API key",
      "password": true
    },
    {
      "id": "SNAPIX_BUCKET_KEY",
      "type": "promptString",
      "description": "Custom bucket key, if you've setup one (optional)",
      "password": false
    }
  ],
  "servers": {
    "metalevel/snapix-mcp": {
      "command": "npx",
      "args": ["-y", "@metalevel/snapix-mcp-server"],
      "env": {
        "SNAPIX_API_KEY": "${input:SNAPIX_API_KEY}",
        "SNAPIX_BUCKET_KEY": "${input:SNAPIX_BUCKET_KEY}" // optional
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "metalevel/snapix-mcp": {
      "command": "npx",
      "args": ["-y", "@metalevel/snapix-mcp-server"],
      "env": {
        "SNAPIX_API_KEY": "your-api-key-here",
        "SNAPIX_BUCKET_KEY": "your-optional-custom-bucket-key"
      }
    }
  }
}

Quick Start - Remote (HTTP)

For clients that support Streamable HTTP transport, point to the hosted endpoint:

https://www.snapix.space/api/mcp

Pass your API key via the Authorization header:

Authorization: Bearer <your-api-key>

The remote endpoint is stateless - no session persistence between requests. It does not support imageFilePath; use imageBase64 for local images (with caution for large files) or imageUrl for publicly accessible URLs. See the full MCP docs for VS Code and Claude Desktop config examples.

Environment Variables

| Variable | Required | Default | Description | | --- | --- | --- | --- | | SNAPIX_API_KEY | Yes | - | Your SnapiX API key | | SNAPIX_BUCKET_KEY | No | primary bucket | Default storage bucket for uploads, generates, and gallery creation | | SNAPIX_LOG_LEVEL | No | warn | SDK log verbosity: debug | info | warn | error | silent |

Available Tools

Each tool carries MCP tool annotations that well-behaved clients (VS Code Copilot, Claude Desktop, etc.) use to show appropriate confirmation prompts. Because SnapiX retains no history and no soft-delete, every update or delete is irreversible — destructiveHint is set to true on all mutating tools accordingly.

| Tool | Description | Credits | Read-only | Destructive | Idempotent | Open-world | | --- | --- | --- | --- | --- | --- | --- | | snapix_get_docs | Fetch SDK, API, MCP, or About documentation | Free | ✓ | n/a | ✓ | – | | snapix_convert_image | Guidance tool - explains how to convert images using the upload tool | Free | ✓ | n/a | ✓ | – | | snapix_upload_image | Upload an image from URL or local file, optionally convert format and resize | 1+ | – | – | – | ✓ | | snapix_generate_image | Generate an image from a text prompt, optionally guided by a template image (Gemini AI)* | 40+ | – | – | – | ✓ | | snapix_list_images | List images with pagination and filtering | Free | ✓ | n/a | ✓ | – | | snapix_get_image | Get full details for a single image | Free | ✓ | n/a | ✓ | – | | snapix_update_image | Update image metadata, gallery assignments, or replace/re-convert the image | Free† | – | ✓ | – | ✓ | | snapix_delete_image | Permanently delete an image | Free | – | ✓ | ✓ | – | | snapix_create_gallery | Create a new gallery, optionally with existing images | Free | – | – | – | – | | snapix_list_galleries | List all galleries | Free | ✓ | n/a | ✓ | – | | snapix_get_gallery | Get gallery details with all images | Free | ✓ | n/a | ✓ | – | | snapix_get_ungrouped_images | Get all images not assigned to any gallery | Free | ✓ | n/a | ✓ | – | | snapix_update_gallery | Update gallery name or visibility | Free | – | ✓ | ✓ | – | | snapix_delete_gallery | Delete a gallery, optionally with all its images | Free | – | ✓ | ✓ | – |

• snapix_generate_image requires a paid subscription. Accepts a text prompt plus an optional template image (URL, local file path, or base64) and generates an image using Gemini AI.

† snapix_update_image is free for metadata-only updates. Costs 1+ App credits when formatOptions, resizeOptions, or a replacement image source is provided.

Resources

MCP Resources provide passive context that AI clients can pre-load without making explicit tool calls.

| URI | Description | | --- | --- | | snapix://galleries | All galleries (name, id, visibility, image count) | | snapix://galleries/{galleryId} | Gallery details with all images and CDN URLs | | snapix://images/ungrouped | All images not assigned to any gallery | | snapix://images | Recent images (first page) with metadata and CDN URLs | | snapix://images/{imageId} | Full image metadata, variants, dimensions, and CDN URLs |

Prompts

MCP Prompts are interactive workflow templates that AI clients can invoke on demand. Clients that support the MCP prompts capability (VS Code Copilot, Claude, and others) expose them as slash commands or selectable actions in the chat interface.

| Prompt | Description | | --- | --- | | snapix_setup_sdk_core | Guided setup of @metalevel/snapix-sdk-core: reads live docs, installs the package with the detected package manager, and appends SNAPIX_* environment variables to the correct .env file |

Rate Limiting

The MCP server respects the same rate limits as the REST API. When a rate limit is hit (HTTP 429), the server returns an MCP error with a retryable flag, signaling to the AI client that it should wait and retry the request.

Credits & Quotas

• Free operations: listing, getting, updating metadata, and deleting images/galleries
• Credit-consuming operations: uploading images (1+ credits), generating images (40+ credits)
• Credit costs follow the same rules as the REST API
• When credits are exhausted, the server returns a clear error message

Programmatic Usage

createSnapixMcpServer creates and returns a configured McpServer instance:

import { createSnapixMcpServer } from "@metalevel/snapix-mcp-server";

const server = createSnapixMcpServer({
  apiKey: process.env.SNAPIX_API_KEY!,
  baseUrl: "https://www.snapix.space",        // optional
  bucketKey: process.env.SNAPIX_BUCKET_KEY,   // optional
  logLevel: "warn",                           // optional: debug | info | warn | error | silent
  transport: "stdio",                         // optional: "stdio" (default) | "http"
});

handleStatelessRequest powers the hosted /api/mcp HTTP endpoint - it is designed for internal server-side usage and is not intended as a general-purpose public API:

import { handleStatelessRequest } from "@metalevel/snapix-mcp-server";

export async function POST(request: Request): Promise<Response> {
  return handleStatelessRequest(request, {
    apiKey: request.headers.get("Authorization")?.replace("Bearer ", "") ?? "",
    bucketKey: request.headers.get("X-Snapix-Bucket-Key") ?? undefined,
  });
}

Documentation

• Full MCP docs
• REST API docs
• Get API key

License

MIT