Skip to main content
Glama
Sign In
@pixelvault-dev/local-mcp

@pixelvault-dev/local-mcp

by pixelvault-dev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

@pixelvault-dev/local-mcp

A local (stdio) MCP server for PixelVault — agent-first image hosting.

The difference from the hosted MCP server (mcp.pixelvault.dev): this one runs on your machine, so it can upload a local file by path. It reads the bytes off disk and streams them to the API as multipart/form-data — the file is never base64-encoded into the model's context. That keeps large images (and slow, token-hungry base64 round-trips) out of the conversation.

Use the hosted server when your client is remote (ChatGPT, etc.); use this one for local coding agents that have files on disk.

Install

Runs with npx — no global install needed:

npx @pixelvault-dev/local-mcp

Related MCP server: image-vision-mcp

Configure

Set your PixelVault API key (a pv_live_… secret key for private uploads):

export PIXELVAULT_API_KEY=pv_live_xxx
# optional: point at a different API
export PIXELVAULT_API_URL=https://api.pixelvault.dev

The server also reads ~/.pixelvault/config.json if you've authenticated with the PixelVault CLI (pixelvault login).

Claude Desktop / MCP client config

{
  "mcpServers": {
    "pixelvault": {
      "command": "npx",
      "args": ["-y", "@pixelvault-dev/local-mcp"],
      "env": { "PIXELVAULT_API_KEY": "pv_live_xxx" }
    }
  }
}

Tools

Tool

What it does

upload_image

Upload by local path (streamed, no base64), or source_url, or data. Optional folder, visibility, expires_in, metadata, describe (AI alt text + caption + OCR in the background; read it with get_image).

list_images

List images in your project (paginated), optionally filtered by custom metadata or searched by AI description (q: alt text, caption, OCR text).

get_image

Metadata for one image by id.

update_image_metadata

Replace an image's custom metadata (replaces, not merges; null clears).

delete_image

Permanently delete an image by id.

sign_url

Mint a time-limited signed URL for a private image.

optimize_image

Compress, resize and convert a local image file on this machine (no API key, nothing uploaded). Writes <name>.optimized.<ext>; never makes a file bigger.

transform_image

Build an on-the-fly transform URL (resize, crop, format, AI background removal, effects).

Every returned CDN URL supports on-the-fly transforms via query params — see the transforms docs.

optimize_image

Runs entirely locally with sharp, an optional dependency: if it can't be installed for your platform the tool returns a sharp_unavailable error and every other tool is unaffected. Needs Node 20.9+. Inputs: path, format (keep|webp|avif|jpg|png, default keep), max_width/max_height (never upscales), quality (default 80), keep_metadata, output_path or in_place, dry_run. EXIF/GPS metadata is stripped by default (orientation is applied first). It refuses to overwrite an existing file (other than *.optimized.*), never follows symlinks, writes atomically, and leaves already-optimal files alone, so it is safe to call repeatedly. The same engine ships in the pixelvault-cli optimize command.

License

MIT

Available Tools

6 tools
delete_imageDelete imageA

Permanently delete one PixelVault image by id (DELETE /v1/images/:id).

Inputs: id (required).

get_imageGet imageA

Get metadata (CDN URL, size, MIME type, dimensions) for one PixelVault image by id (GET /v1/images/:id). The returned CDN URL supports on-the-fly transforms via query params — e.g. ?w=400&fit=cover (resize/crop), ?fmt=webp (format), ?segment=foreground (AI background removal → transparent PNG), and effects like ?blur=30&saturation=0&rotate=90. Or call transform_image to build a valid transform URL for you. See https://pixelvault.dev/docs#transforms.

Inputs: id (required).

list_imagesList imagesA

List images in your PixelVault project, most recent first (GET /v1/images), paginated via page/per_page. The returned CDN URL supports on-the-fly transforms via query params — e.g. ?w=400&fit=cover (resize/crop), ?fmt=webp (format), ?segment=foreground (AI background removal → transparent PNG), and effects like ?blur=30&saturation=0&rotate=90. Or call transform_image to build a valid transform URL for you. See https://pixelvault.dev/docs#transforms.

Inputs: page, per_page.

sign_urlSign private URLA

Mint a time-limited signed URL for a private image (POST /v1/images/:id/sign-url). The signature binds the image, so the URL can't be replayed against another; strip it and the CDN returns 403. Optional expires_in (seconds, default 3600).

Inputs: id (required), expires_in.

transform_imageBuild transform URLA

Build an on-the-fly transform URL for a PixelVault image (resize, crop, format/quality, AI background removal, blur/sharpen/rotate/flip, brightness/contrast/saturation, and same-project watermark tiling). Provide exactly one of url (a PixelVault CDN URL) or id (resolved via the API), plus one or more transform params. See https://pixelvault.dev/docs#transforms.

Inputs: id, fit, url, blur, +16 more.

upload_imageUpload imageA

Upload an image to PixelVault and get an instant CDN URL. Prefer path — a LOCAL file path the server reads off disk and streams — so large files aren't base64-encoded into the model context. Alternatively pass source_url (a public https URL the API imports) or data (base64 bytes). Optional folder, filename, visibility (private → signed URL, needs a secret key), expires_in (auto-expiring image), sign_expires_in. Max 5 MB; JPG/PNG/GIF/WebP/AVIF/SVG. The returned CDN URL supports on-the-fly transforms via query params — e.g. ?w=400&fit=cover (resize/crop), ?fmt=webp (format), ?segment=foreground (AI background removal → transparent PNG), and effects like ?blur=30&saturation=0&rotate=90. Or call transform_image to build a valid transform URL for you. See https://pixelvault.dev/docs#transforms.

Inputs: data, path, folder, filename, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.2/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a distinct purpose: uploading, listing, retrieving metadata, deleting, signing URLs, and building transform URLs. No functional overlap.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (e.g., upload_image, list_images, get_image), making the set predictable.

    Tool Count5/5

    6 tools is appropriate for an image management server—neither too few nor too many, covering essential operations without redundancy.

    Completeness4/5

    The server covers upload, list, get, delete, signing, and transform URL generation. Missing an update/rename tool for metadata, but the core lifecycle is well-represented.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers