← Back to blog

Local Image Editing and OCR for AI Agents (No Uploads)

September 14, 2026 · Eric · 8 min read

Most media APIs work the same way: hand over a public URL, a remote service does the work, you wait for a link back. Good for a generated hero image or a 200-page PDF split. Wrong for a client contract, a medical scan, a passport photo, or a screenshot full of internal URLs — and overkill when your agent just needs to shrink a logo.

The Agent Media Tools local MCP server covers that second case. It exposes two tools that never touch the network: edit_image_easy for resize, compress, convert, and grayscale, and extract_document_easy for text, PDF, and image OCR. Files stay on your disk, the work runs in the MCP server process, and no API key or credit is consumed.

What "local" means in this server

Every tool in the pack is classified by where its work happens, and the Easy Mode runner enforces that classification:

Hosted image generation has its own switch, AMT_ALLOW_HOSTED_IMAGE_FALLBACK=true. The design goal: a model cannot quietly escalate from "resize this screenshot" to "upload this screenshot to a third party."

Install the local bridge pack

Step 1

Download the bridge pack from the Easy Mode setup guide (direct link: /downloads/agent-media-tools-local-bridge.zip) and extract it. Node.js 18 or newer is required.

Step 2

Run npm install inside the extracted folder — that pulls in the MCP SDK and sharp, with the native image binary for your OS.

Step 3

Register the bundled MCP server in your host. For a YAML-style host such as Hermes Agent, the block looks like this:

mcp_servers:
  media-tool:
    command: "node"
    args: ["/absolute/path/to/bridge/mcp-server.js"]
    env:
      MEDIA_TOOL_URL: "https://agentmediatools.com"
      AMT_EASY_MODE: "true"

MEDIA_TOOL_URL only matters for hosted tools. Leave the remote switches unset and the server still exposes the full local set.

With AMT_EASY_MODE=true the model sees a compact control layer — the discovery/execution controls plus the local media workflows — instead of the entire catalog. Unset it and the detailed legacy schemas appear too.

edit_image_easy: resize, compress, convert, grayscale

One tool covers the four operations agents ask for most, all through sharp against a path you control.

ArgumentAcceptsNotes
file_pathAbsolute or relative pathRequired. Input capped at 50 MB.
actionresize · compress · convert · grayscaleDefaults to compress.
width / heightInteger 16–8192resize requires at least one. Uses fit: inside, so aspect ratio is preserved.
formatjpeg · png · webpDefaults to png for PNG inputs, jpeg otherwise.
qualityInteger 1–100Defaults to 82. Used for JPEG and WebP output; PNG uses maximum compression.
allow_enlargeBooleanDefaults to false — a resize never upscales unless you ask for it.

A typical model-issued call looks like this:

{
  "tool": "edit_image_easy",
  "arguments": {
    "file_path": "/home/you/photos/IMG_2041.png",
    "action": "resize",
    "width": 1600,
    "format": "webp",
    "quality": 78
  }
}

The response confirms what landed on disk, including real dimensions and byte count — useful when an agent must decide whether another pass is needed:

{
  "success": true,
  "provider": "local",
  "action": "resize",
  "file": "/home/you/bridge/outputs/IMG_2041-resize-9c1f2ab4.webp",
  "format": "webp",
  "width": 1600,
  "height": 1067,
  "bytes": 214883
}

Outputs default to an outputs folder next to the bridge. Set AMT_LOCAL_MEDIA_OUTPUT_DIR to pin them somewhere a later step can predict.

extract_document_easy: text, PDF, and OCR without uploading

This replaces the "email me the PDF and I'll paste it into a chat" workflow. The method depends on the file extension:

{
  "tool": "extract_document_easy",
  "arguments": {
    "file_path": "/home/you/scans/invoice-2214.pdf",
    "max_characters": 40000
  }
}
{
  "success": true,
  "provider": "local",
  "method": "local-pdftotext",
  "text": "INVOICE 2214\n...",
  "characters": 3187,
  "truncated": false
}

Two limits matter before you wire this into a loop: the 50 MB file cap, and max_characters, which defaults to 100,000 (range 100–500,000). The truncated flag is set honestly, so an agent can tell "the document is short" from "I only read the first slice."

Both tools use system binaries rather than bundling them: PDF extraction needs pdftotext on your PATH, image OCR needs tesseract. A missing binary produces a direct error naming the command — a better failure mode for an autonomous agent than a silent empty result. Install them with brew install poppler tesseract (macOS) or apt install poppler-utils tesseract-ocr (Linux).

Optional: local image generation in the same pack

The pack also ships create_image_easy, which turns a plain-language request into an image on local hardware. With provider: "auto" it probes ComfyUI at AMT_COMFYUI_URL (default http://127.0.0.1:8188), then Stable Diffusion WebUI at AMT_SD_WEBUI_URL (default http://127.0.0.1:7860), writing to AMT_LOCAL_IMAGE_OUTPUT_DIR. Aspect presets: square 1024×1024, portrait 768×1024, landscape 1024×768.

If no local generator is available the tool fails with a clear message rather than silently billing you; hosted fallback requires AMT_ALLOW_HOSTED_IMAGE_FALLBACK=true plus a key. The editing and extraction tools have no hosted path at all.

Letting the model find these tools on its own

You do not have to hard-code tool names. Give the model find_tools_easy with the user's own words and it returns the best few matches with a simplified schema and a privacy label:

{
  "tool": "find_tools_easy",
  "arguments": {
    "request": "locally resize this picture and read the text off this scan",
    "limit": 5
  }
}

Wording matters here. Requests containing "local", "privately", "offline", or "do not upload" bias the ranking toward local tools, and every result is tagged local, remote, or sensitive_remote. run_tool_easy then executes the chosen name; a remote tool the human has not enabled fails with an explicit message instead of uploading anything.

When several deterministic steps are needed, run_workflow_easy chains up to 12 tools in order and lets a later step reference an earlier JSON result with $steps.STEP_ID.path:

{
  "steps": [
    { "id": "encoded", "tool": "base64_encode", "arguments": { "text": "hello" } },
    { "id": "decoded", "tool": "base64_decode", "arguments": { "base64": "$steps.encoded" } }
  ]
}

Workflows run sequentially, reject missing references and duplicate IDs, refuse recursive calls into the meta-tools, and stop on the first failure unless a step sets continue_on_error.

Driving it with curl and Python

The pack also runs an OpenAI-compatible bridge on loopback (127.0.0.1:3333 by default). Even if you never point a local model at it, the bridge is a handy local control plane for scripts:

curl -s http://127.0.0.1:3333/health
# {"success":true,"service":"agent-media-tools-local-bridge","local_history":true,"intelligence":true,...}

It keeps a bounded history of tool-using runs — tool names, arguments, timing, errors, token usage, and the local/remote classification. Prompt text and model prose are never stored.

curl -s http://127.0.0.1:3333/amt/runs
curl -s http://127.0.0.1:3333/amt/workflows

# save a successful run as a replayable workflow, then run it again later
curl -s -X POST http://127.0.0.1:3333/amt/runs/<run_id>/workflow \
  -H "Content-Type: application/json" -d '{"name":"Receipt to text"}'
curl -s -X POST http://127.0.0.1:3333/amt/workflows/<workflow_id>/run

There is also a local compression workflow for when "small enough" is a number rather than a vibe. Register a file once, then name a byte target; the workflow tries bounded quality steps, preserves dimensions, and verifies the real output size before reporting success:

curl -s -X POST http://127.0.0.1:3333/amt/intelligence/artifacts \
  -H "Content-Type: application/json" \
  -d '{"file_path":"/home/you/photos/receipt.png","kind":"image"}'
# {"success":true,"artifact":{"artifact_id":"artifact_...","name":"receipt.png",...}}
curl -s -X POST http://127.0.0.1:3333/amt/intelligence/workflows/compress-image \
  -H "Content-Type: application/json" \
  -d '{"artifact_id":"artifact_...","target_size_bytes":2000000,"format":"webp"}'
# {"success":true,"workflow":"compress_image_to_target","goal_met":true,
#  "output_artifacts":[...],"important_values":{...},"next_action":null}

Targets range from 16,384 bytes to 52,428,800 bytes (16 KB–50 MB), and format is optional (jpeg or webp). If the target is unreachable the response returns goal_met: false plus a next_action. These endpoints never return local filesystem paths; artifacts stay behind opaque IDs.

One nuance for anyone scripting against the bridge: non-GET requests under /amt/ are rejected when they carry a non-loopback Origin header, so a random web page cannot drive your control plane. curl and Python send no origin and work normally from the same machine.

Here is the same flow in Python with requests:

import requests

BRIDGE = "http://127.0.0.1:3333"

# 1. Register a local file by path. The bridge returns an opaque artifact id.
registered = requests.post(
    f"{BRIDGE}/amt/intelligence/artifacts",
    json={"file_path": "/home/you/photos/receipt.png", "kind": "image"},
    timeout=30,
).json()
artifact_id = registered["artifact"]["artifact_id"]

# 2. Ask for a byte target; the workflow picks quality steps and verifies output.
result = requests.post(
    f"{BRIDGE}/amt/intelligence/workflows/compress-image",
    json={"artifact_id": artifact_id, "target_size_bytes": 2_000_000, "format": "webp"},
    timeout=120,
).json()

print(result["goal_met"], result["summary"])
print(result["output_artifacts"])

Local vs hosted: pick per file, not per project

SituationUse
Client contracts, scans, screenshots, anything regulated or embarrassingextract_document_easy / edit_image_easy — files never leave the machine
Bulk format conversion inside a build or export stepLocal tools; no rate limits, no credits, no network dependency
Hundreds of files, many machines, or a hosted pipelineHosted routes, where the server owns the compute and the queue
OCR where layout fidelity matters more than privacyHosted extraction options, then keep the local tool for the private subset

The honest boundaries of the local path: it needs real binaries and a real disk, it is one machine's worth of throughput, and the file cap is 50 MB. It fits private, repetitive, agent-driven file work — not a hosted media pipeline.

Run it on your own machine

Download the local bridge pack, wire it into your MCP host, and process a file without it ever leaving your laptop.

Set up the local bridge

Prefer the hosted toolbox for public files? Most tools here have a hosted sibling that takes a URL and returns a link — browse the toolbox, or read the image pipeline guide for hosted chaining patterns.