Kompressr

@kompressr/mcp-server

Kompressr tools for MCP agents: upload files, wait for processing, generate private links, paginate uploads and permanently delete explicit asset IDs. File operations use the separate @kompressr/sdk package. Applications can use that SDK directly without starting MCP.

Requires Node.js 22 or later. For a desktop client that supports MCPB extensions, download a Kompressr MCP bundle from GitHub Releases and follow the desktop installation guide.

Setup

Create a Kompressr account and start the 30-day image-upload trial or choose a paid plan. In Dashboard → Projects, open the project and choose API Keys. Keep project/master keys on trusted machines; use scoped keys for individual application or agent runtimes. The project UUID is needed only for listing uploads.

Configure an MCP client to run the package:

{  "mcpServers": {    "kompressr": {      "command": "npx",      "args": ["-y", "@kompressr/[email protected]"],      "env": {        "KOMPRESSR_API_KEY": "YOUR_PROJECT_OR_SCOPED_KEY",        "KOMPRESSR_PROJECT_ID": "YOUR_PROJECT_UUID"      }    }  }}

KOMPRESSR_PROJECT_ID is required for upload listing; upload/status/signing/deletion need only the key. For source builds, follow CONTRIBUTING.md, then configure node with the absolute path to this package's built dist/index.js.

Configuration and migration

Production defaults to https://kompressr.com for management and https://uploads.kompressr.com for upload bodies. For another deployment, supply KOMPRESSR_API_URL and KOMPRESSR_UPLOAD_BASE_URL from private runtime configuration. Custom management origins use the same upload origin unless overridden. Origins must use HTTP(S) without credentials, paths, queries or fragments.

Saved configuration remains ~/.kompressr/config.json:

{  "api_key": "YOUR_KEY",  "project_id": "YOUR_PROJECT_UUID",  "api_url": "https://kompressr.com",  "upload_url": "https://uploads.kompressr.com"}

Environment settings override saved values. A different environment key does not inherit the saved project or endpoint, which prevents mixing accounts; supply those explicitly for custom origins. A changed management origin re-derives uploads unless an upload override is provided. Old saved https://api.kompressr.com values migrate in memory to production. New saves use atomic replacement and permissions 0700 for the directory, 0600 for the file; existing files are not rewritten merely by loading. Keep keys and configuration out of source control.

File workflow

1. Call upload_asset with exactly one file_path or file_url. Save the returned numeric asset_id.
2. Call wait_for_asset or get_asset_status. Acceptance and a pending URL do not mean the file is ready; use the current processed response only for active assets.
3. Share a public processed URL, or authorize the private recipient in your app and call generate_private_url for a fresh expiring link.
4. On wait timeout, resume with the saved ID. Do not upload again to recover from a polling timeout.

The 30-day free trial includes 100 image uploads total, shared across API, SDKs, MCP and dashboard. This allowance does not renew monthly. Formats, size, video quality and private delivery remain plan/project dependent. The SDK sends all multipart options before the file, as required by the streaming API.

Tools

Missing/blank filenames in historical status/list records remain valid; listing displays “Unnamed file” without changing response metadata.

All file tools return readable text, a JSON text block and structuredContent; failures set isError. Numeric IDs must be positive safe integers (single-ID tools also accept numeric strings).

Processing status and deletion status are separate. Permanent deletion removes files later; cached, downloaded and offline copies may remain. Retrying the same old ID cannot delete a replacement with a new ID. Bulk deletion preserves partial failure and does not automatically expand or retry a selection. storage_credited_mb is recorded storage credit in MB, not a cash refund. Other size fields are bytes.

Read tools carry read-only annotations; deletion tools carry destructive annotations. Annotations describe behavior; server authorization and the MCP client's approval controls enforce access.

Keys, errors and remote files

Use a scoped key for one customer/agent runtime. The server enforces identity, allowed file types/visibility and action scopes. Default scopes exclude delete; provisioning must opt into it. Scoped keys cannot call platform administration or URL Prepend/source optimization. Provision identities and keys from your trusted backend with the SDK's client.platform group or the existing platform APIs. No master-key administration tools are added to MCP.

Safe GET requests retry network/429/502/503/504 failures at most twice within a 30-second request deadline and respect Retry-After. Uploads default to a 10-minute deadline; writes are never automatically replayed. Structured errors preserve code, kind, HTTP status and, where relevant, assetId/mayHaveSucceeded. A dispatched write interrupted or returning malformed JSON/data may have succeeded; inspect the outcome before repeating it. Arbitrary errors and raw gateway bodies are not exposed.

file_url downloads on the MCP machine, then uploads a local temporary file. MCP cancellation/disconnection, including stdin EOF, aborts the transfer and is checked again before starting the upload. Before dispatch no asset is created; after dispatch a server-accepted upload cannot be rolled back by client cancellation. It streams to disk with a 2 GiB transport ceiling, five-minute download deadline and at most five redirects. HTTPS cannot downgrade to HTTP. Numeric CIDR checks admit ordinary global IPv6 unicast and conservatively exclude IETF protocol, transition and documentation ranges, including their compressed forms. Each destination resolves to validated allowed addresses used for the connection; private/local destinations require exact hostnames in KOMPRESSR_REMOTE_ALLOWED_HOSTS. Redirect targets are checked again. Sources use no Kompressr credentials. Temporary files are restricted and cleaned up on success/failure. The transport ceiling does not override your plan or disk capacity; remote download and upload have separate deadlines. Server-side URL import is not part of this SDK/MCP integration.

See CHANGELOG.md and the contribution guide. Local HTTP/protocol checks do not certify deployed authentication, processing or CDN behavior. The source verification commands use local fixtures and do not publish packages.