Kompressr — Claude Code MCP server: upload and optimize files
An MCP server that uploads files, waits for processing and hands back private delivery links from inside your agent. Useful when the agent has to publish an image or video.
claude mcp add --env KOMPRESSR_API_KEY=<KOMPRESSR_API_KEY> --env KOMPRESSR_PROJECT_ID=<KOMPRESSR_PROJECT_ID> --transport stdio mcp-server -- npx -y @kompressr/mcp-serverWhat Kompressr does
Kompressr exposes file tools to the agent. upload_asset takes exactly one file_path or file_url, wait_for_asset polls until the job finishes, and generate_private_url mints a fresh link with an expiry. Rounding it out: list_assets with paging, get_asset_status, and delete_asset for permanent removal by explicit ID.
Node.js 22 or newer is required. Configuration needs KOMPRESSR_API_KEY, plus KOMPRESSR_PROJECT_ID if you want to browse uploads. Skip the project UUID and list_assets will not work — check that before the first run. Keep keys on trusted machines and out of source control.
Processing state and deletion state are tracked separately. A private link expiring does not remove the file. Deletion starts background cleanup and cannot be undone, and cached or downloaded copies may survive. When wait_for_asset times out, do not re-upload: keep the asset_id and resume with it.
What it helps with
- push a file into storage from the agent
- wait for video processing instead of guessing
- hand a client a temporary private link
- find an upload by status or external_id
- delete a batch of assets by explicit IDs
Example prompts for the agent
- Upload
preview.pngthrough Kompressr and wait until it is ready - Generate a private link for asset 4821 that lasts an hour
- List my failed uploads on page two
How to install Kompressr
Platform CLI
claude mcp add --env KOMPRESSR_API_KEY=<KOMPRESSR_API_KEY> --env KOMPRESSR_PROJECT_ID=<KOMPRESSR_PROJECT_ID> --transport stdio mcp-server -- npx -y @kompressr/mcp-serverReplace <…> with your own values
Platform CLI
codex mcp add mcp-server --env KOMPRESSR_API_KEY=<KOMPRESSR_API_KEY> --env KOMPRESSR_PROJECT_ID=<KOMPRESSR_PROJECT_ID> -- npx -y @kompressr/mcp-serverReplace <…> with your own values
Config file
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@kompressr/mcp-server"
],
"env": {
"KOMPRESSR_API_KEY": "<KOMPRESSR_API_KEY>",
"KOMPRESSR_PROJECT_ID": "<KOMPRESSR_PROJECT_ID>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@kompressr/mcp-server"
],
"env": {
"KOMPRESSR_API_KEY": "<KOMPRESSR_API_KEY>",
"KOMPRESSR_PROJECT_ID": "<KOMPRESSR_PROJECT_ID>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e KOMPRESSR_API_KEY=<KOMPRESSR_API_KEY> -e KOMPRESSR_PROJECT_ID=<KOMPRESSR_PROJECT_ID> mcp-server npx -y @kompressr/mcp-serverReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Kompressr
How do I install Kompressr in Claude Code?
Run claude mcp add kompressr -e KOMPRESSR_API_KEY=<KOMPRESSR_API_KEY> -- npx -y @kompressr/mcp-server. Add KOMPRESSR_PROJECT_ID as well if you need upload listing.
What does Kompressr do?
It gives the agent tools to upload files, wait for processing, issue private links and delete assets by ID. File operations live in the separate @kompressr/sdk package.
What do I need to run Kompressr?
Node.js 22 or later and a KOMPRESSR_API_KEY from the project dashboard. Upload listing also needs the project UUID in KOMPRESSR_PROJECT_ID.
