image_base64 MCP tool: images to data URIs in an AI agent

Embedding a small icon as a data URI in CSS or an email template is a routine job, and one an assistant can’t do on its own. It can’t see the bytes of icon.png, and it can’t produce Base64 for them, so it ends up writing a placeholder. The reverse happens too: a JSON payload or a log contains a Base64 blob that is supposedly an image, and you want to know what it is and look at it.

The devtoolbox.cc MCP server has a tool for both directions, image_base64. It reads an image file and returns a ready-to-paste data URI, or decodes Base64 and writes the image to a file. It’s the same code as the Image to Base64 converter on this site. Setup is described on the MCP page.

What the tool does

In encode mode it reads an image file and returns:

• the real image type, detected from the file’s bytes rather than its name (PNG, JPEG, GIF, WebP, BMP, ICO, AVIF or SVG);
• the pixel dimensions, where the format makes them available;
• the file size and the size of the data URI, with the increase in percent;
• the data:<type>;base64,… URI itself.

In decode mode it accepts a data URI or bare Base64 (standard or URL-safe, padding optional), checks that the decoded bytes really are an image, warns when a data URI claims a different type than the bytes show, and writes the image to output_path.

Arguments

Argument	Type	Meaning
mode	"encode" or "decode"	Required.
path	string	The image file to encode.
base64	string	Base64 or a data URI to decode.
output_path	string	Encode: write the data URI to a file. Decode: write the image.
overwrite	boolean	Allow replacing an existing file. Default false.

Examples

These examples were run against the real tool. An SVG icon from a project:

<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16"><path d="M3 8l3 3 7-7" fill="none" stroke="#16a34a" stroke-width="2"/></svg>

{ "mode": "encode", "path": "/home/dev/site/icons/check.svg" }

Type: SVG (image/svg+xml), 16 × 16 px, 160 B
Data URI: 242 B (+51%)

data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgdmlld0JveD0iMCAwIDE2IDE2Ij48cGF0aCBkPSJNMyA4bDMgMyA3LTciIGZpbGw9Im5vbmUiIHN0cm9rZT0iIzE2YTM0YSIgc3Ryb2tlLXdpZHRoPSIyIi8+PC9zdmc+Cg==

The URI can go straight into CSS as background-image: url("data:…") or into an <img src>. For larger images, write the URI to a file instead of into the conversation:

{
  "mode": "encode",
  "path": "/home/dev/site/icons/check.svg",
  "output_path": "/home/dev/site/icons/check.svg.txt"
}

Wrote 242 bytes to /home/dev/site/icons/check.svg.txt
Type: SVG (image/svg+xml), 16 × 16 px, 160 B
Data URI: 242 B (+51%)

Decoding a 1 × 1 GIF from a data URI and saving it:

{
  "mode": "decode",
  "base64": "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7",
  "output_path": "/home/dev/tmp/pixel.gif"
}

Type: GIF (image/gif), 1 × 1 px, 42 B
Wrote 42 bytes to /home/dev/tmp/pixel.gif

That’s the classic tracking pixel from countless email templates. When a data URI claims a type that doesn’t match its bytes, the tool says so. Browsers often show such images anyway, but other software may reject them:

{
  "mode": "decode",
  "base64": "data:image/png;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7",
  "output_path": "/home/dev/tmp/pixel2.gif"
}

Type: GIF (image/gif), 1 × 1 px, 42 B
Warning: The data URI is declared as image/png, but the data is a GIF image.
Wrote 42 bytes to /home/dev/tmp/pixel2.gif

And Base64 that decodes to something other than an image is rejected, rather than saved under an image name:

{
  "mode": "decode",
  "base64": "SGVsbG8sIHdvcmxkIQ==",
  "output_path": "/home/dev/tmp/not-an-image.png"
}

The decoded data is not a recognised image (PNG, JPEG, GIF, WebP, BMP, ICO, AVIF or SVG)

The type comes from the bytes

File names and declared types are often wrong. Logos get saved with the wrong extension, CMS exports rename everything to .png, and a data URI copied from an old stylesheet may say image/png for a JPEG. The tool looks at the first bytes of the file, where every image format has its own signature, and reports what the data really is. This file is called logo.png, but it contains SVG:

<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32"><circle cx="16" cy="16" r="14" fill="#4f46e5"/></svg>

{
  "mode": "encode",
  "path": "/home/dev/site/logo.png",
  "output_path": "/home/dev/site/logo.uri.txt"
}

Wrote 182 bytes to /home/dev/site/logo.uri.txt
Type: SVG (image/svg+xml), 32 × 32 px, 117 B
Data URI: 182 B (+56%)

The data URI uses image/svg+xml, the type browsers need to render it, not the type the name suggests.

Things to ask your assistant

• “Inline assets/logo.svg as a data URI in the .brand rule of email.css.”
• “The avatar field in user.json is Base64. What kind of image is it? Save it as a file with the right extension.”
• “Which icons in public/icons/ are under 2 KB? Inline those in sprite.css.”
• “Check the data URIs in newsletter.html: do their declared types match the actual image data?”

To convert a single image in the browser, with a preview and copy-ready CSS, HTML and Markdown snippets, use the Image to Base64 converter. Base64 for any other kind of file is handled by the Base64 tool.

When a data URI is the right choice

Base64 makes data about a third larger, and an inlined image can’t be cached separately from the page or stylesheet that contains it. Data URIs pay off for small images that every page needs anyway: icons, small logos, simple backgrounds, and images in HTML emails, where external images are often blocked. For photos and anything larger than a few kilobytes, a normal image file is faster. The encode output shows both sizes, so the agent can make that call per file. The article on data URIs has more detail on the trade-offs.

Install

image_base64 is part of the devtoolbox.cc MCP server, which runs locally and makes no network requests. Images and the data inside them stay on your computer. Setup for Claude Desktop, Claude Code, Cursor and VS Code is on the MCP install page.