Try Online Pricing Compare Blog Creator 日本語

Blog

Have Claude Compress Your Images: Karui MCP Server Setup and Examples

Opening an app just to shrink an image is an extra step. This post replaces that step with a conversation. Once you register the Karui MCP server in Claude Desktop, saying "Compress the photo on my desktop for the web" runs the compression. The setup is a single entry in a JSON file.

Photo of hands on the keyboard of a laptop with a chat screen open. One photo thumbnail is visible on the screen

What MCP is

MCP (Model Context Protocol) is a standard for giving AI clients access to external tools. The server lists the tools it offers, and the client calls the ones it needs as the conversation goes.

The Karui MCP server runs on JSON-RPC 2.0 over stdio and supports MCP revision 2025-06-18. It has no network access, and all compression happens locally.

How Karui MCP is set up. It does not open any ports either.

Why use MCP for image compression

There are three reasons.

First, no upload is needed. Karui MCP takes a local file path and compresses on the same machine. It does not send image data to an external API.

Second, results are reproducible. preset: web is 1600px at quality 75. These are the same settings as the CLI preset, so the numbers do not drift from one conversation to the next.

Third, the free tier and license are shared with the GUI. The allowance of 20 files a day and the $29 Pro license are the same. You do not need a separate contract for MCP.

Interface How you use it Best for
GUIDrag and dropProcessing a few images while previewing
CLICommandsScripting high-volume and scheduled jobs
MCPConversationShrinking one image on the spot without doing it by hand

All three use the same engine and the same quota. MCP is an entry point that saves you opening the app, not a separate product.

Setting up Karui MCP

Find the binary

install.sh installs both karui and karui-mcp. First, check where it is.

curl -fsSL https://karui.app/install.sh | sh
which karui-mcp

It is typically at /Users/yourname/.local/bin/karui-mcp. If you build from source, cargo build --release -p karui-mcp produces it at karui-app/src-tauri/target/release/karui-mcp.

Write the config JSON

On macOS the config file is ~/Library/Application Support/Claude/claude_desktop_config.json. Add karui to your existing mcpServers.

{
  "mcpServers": {
    "karui": {
      "command": "/Users/yourname/.local/bin/karui-mcp"
    }
  }
}

command must always be an absolute path. ~ is not expanded inside the JSON. Paste the output of which karui-mcp as is.

If other servers are already there, add it inside mcpServers with a comma. JSON does not allow comments or trailing commas. Run it through your editor's syntax check before saving.

Restart the client

The config is read at startup. Quit Claude Desktop completely and reopen it. On macOS, use Quit from the menu. Closing the window alone does not reload it. After restarting, if karui appears in the tool list, it worked.

The three available tools

The server exposes only three tools.

Tool What it does Main arguments
compress_imageCompresses one imageinput_path, output_path?, format?, quality?, max_edge?, preset?
compress_pdfCompresses a PDFinput_path, output_path?, quality?
get_image_infoReturns width, height, format, and sizepath

preset has three options: hi, web, and light. format is jpeg, png, or webp. If you specify quality and max_edge individually, you do not need a preset.

Arguments are passed to the tool as JSON, in a form like this.

{"input_path":"/Users/me/Desktop/photo.jpg","preset":"web","output_path":"/Users/me/Desktop/out/photo.jpg"}

Use get_image_info to check a file before compressing. To see your remaining quota, run karui status in a terminal.

Example conversation: compressing a desktop photo for the web

Say "Compress the photo on my desktop for the web." The client picks compress_image from the tool list, puts together preset: web and the desktop path, and makes the call. The model decides on its own, so you do not need to memorize command names.

The process has three stages.

  1. Check the target's width, height, and size with get_image_info (optional)
  2. Run compress_image with preset: web
  3. Check the returned output path and compressed size

For a PDF, "Make this PDF smaller" calls compress_pdf. Set the quality with quality. The practical benefit of this setup is not having to open separate apps for images and PDFs.

That said, which tool gets chosen and how depends on the model and the client's implementation. Model names and on-screen wording change. For setup steps, always give priority to the client's official documentation.

Actual karui-mcp response
# get_image_info
/tmp/karui-demo/jpg/photo-01.jpg: 3504x2336 jpeg 3.46 MB

# compress_image (preset: web)
Compressed /tmp/karui-demo/jpg/photo-01.jpg -> /tmp/karui-demo/jpg/mcp-out/photo-01.jpg (3.46 MB -> 249.4 KB, 93.0% smaller, 1600x1067).
The response text from calling karui-mcp directly over stdio. This is not the Claude Desktop screen. If the output folder does not exist you get an error, so create it first.

Compression you can call from a conversation, free for 20 files a day

Try Karui Free

Common snags and differences from other MCP servers

Use absolute paths

~ and relative paths do not work in some situations. Use absolute paths confirmed with which and pwd. Paths with spaces can be written as is, since they are JSON strings.

stdio only, no open ports

There is no setting for an HTTP URL or port. You point command at the binary. The server connects to the client's stdio, and the process ends when the client exits.

Restart after changing the config

Saving alone does not apply changes. Quit completely, then relaunch. If changes do not take effect, suspect the JSON syntax. Trailing commas, curly quotation marks, and the nesting of mcpServers: these three cause most of the trouble.

Check permissions and that the file exists

When working with files in your Desktop or Documents folder, macOS may ask for file access permission. Without it, the server cannot open the file. If you pass a path that does not exist, the tool returns an error. Errors are passed to the model as results, so you can see what happened in the conversation.

Differences from other MCP servers

Karui MCP does not do image generation or cloud integration. All it does is compress local files and get information about them. It has no network access and needs no API key. It runs synchronously and does not stay running in the background. With only three tools, its setup and behavior are easy to follow.

It is not a do-everything server. Use it as a tool focused on one thing: making images and PDFs smaller.

Try Karui Free

Shrink images locally, from a conversation

No credit card, free for 20 files a day. If you like it, $29 once (perpetual license + 1 year of updates).

Windows 10+ / macOS 12.0+ / 100% local processing

FAQ

Does the MCP server stay running in the background?

No. It starts when called and exits when the work is done. It is not a process waiting in the background, so it does not sit in memory when you are not using it.

Can I use it with clients other than Claude Desktop?

Yes, with any client that supports MCP. It communicates using JSON-RPC 2.0 over stdio and supports MCP revision 2025-06-18. The config file location and format vary by client.

Are my images sent anywhere?

Karui MCP has no network access, and images are processed locally. What reaches the tool is the file path and arguments. Transmission of the conversation itself is governed by how Claude Desktop works.

Is the free tier separate from the GUI?

No, it is the same. The GUI, CLI, and MCP share 20 files a day. The $29 one-time Pro license is also shared, and there is no extra license for MCP.

Can it compress HEIC and PDF too?

On macOS, HEIC/HEIF can be used as input. PDFs are compressed with compress_pdf. Windows/Linux builds have HEIC/HEIF/AVIF decoding disabled.