Repository navigation
images.py example returns raw pixels from tobytes() labelled image/png, so clients cannot decode the thumbnail #3805
Description
Initial Checks
- I confirm that I'm using the newest release of my line (the latest 2.x, or the latest 1.x if I'm still on v1)
- I confirm that I searched for my issue in https://github.com/modelcontextprotocol/python-sdk/issues before opening this issue
Release line
2.x (current stable)
Description
create_thumbnail in examples/snippets/servers/images.py returns Image(data=img.tobytes(), format="png"). Pillow's tobytes() gives raw pixel data, not a PNG file, so the tool sends 22,500 bytes of raw RGB labelled image/png, and a client cannot decode them. The ImageContent schema asks for "the base64-encoded image data" with its MIME type, and docs/servers/media.md names Pillow output as the data= case and warns that a client handed the wrong type "faithfully fails to decode it".
On main this example is no longer rendered into the docs or imported by tests/server/mcpserver/test_integration.py, so it could be fixed or deleted. The copy readers see is the rendered block at docs/server.md:688 on v1.x.
The fix is two lines: buf = io.BytesIO(); img.save(buf, format="PNG"), then pass buf.getvalue().
Example Code
import base64, io, sys, anyio
import mcp
from PIL import Image as PILImage
sys.path.insert(0, sys.argv[1]) # tree root, for examples.snippets
from mcp import Client
from examples.snippets.servers.images import mcp as server
print(mcp.__file__)
PILImage.new("RGB", (400, 300), (200, 30, 30)).save("in.png")
async def main():
async with Client(server) as c:
r = await c.call_tool("create_thumbnail", {"image_path": "in.png"})
block = r.content[0]
raw = base64.b64decode(block.data)
print(block.mime_type, len(raw), "bytes, starts", raw[:8])
try:
print(PILImage.open(io.BytesIO(raw)).format)
except Exception as e:
print(type(e).__name__, e)
anyio.run(main)$ .venv/bin/python ../repro_thumbnail.py $PWD
.../src/mcp/__init__.py
image/png 22500 bytes, starts b'\xc8\x1e\x1e\xc8\x1e\x1e\xc8\x1e'
UnidentifiedImageError cannot identify image file <_io.BytesIO object at 0x79f9afe5c950>
# not run: a real client such as Claude Desktop
Python & MCP Python SDK
Python 3.14.7
mcp at main d7845c0; the v1.x branch at 52e64dd has the same snippet in docs/server.md
I can send that fix for main, with images added to the test_integration.py imports, if you assign this to me. Whether v1.x needs it is your call.
Activity
Techsynx commentedon Nov 3, 2026
Hi! I've opened a fix for this in #3809. It switches
img.tobytes()toio.BytesIO()+img.save(buffer, format="PNG")so that valid PNG containers and chunks are returned, and adds an integration test verifying decoded PNG bytes and dimensions.Could a maintainer please assign this issue to @Techsynx to align with the repository's PR intake policy? Thank you!
Techsynx commentedon Nov 3, 2026
Reproduction & Technical Analysis
I confirmed the reproduction on Python 3.13 / Pillow 11.1.0:
Why it happens
img.tobytes()extracts uncompressed raw raster scanline bytes from memory (len = 100 * 100 * 3 = 30,000bytes) with zero file headers or chunk frames. Returning this withformat="png"(MIMEimage/png) produces invalid PNG streams that standard viewers and PIL reject.Verified Solution
Writing to an in-memory stream via
io.BytesIO():This produces valid PNG byte streams (with standard
PNGmagic bytes\x89PNG\r\n\x1a\nandIHDR/IDAT/IENDchunks) and correctly decodes across clients.We have this fix implemented and verified with an integration test in PR #3809 (
tests/server/mcpserver/test_integration.py::test_images_thumbnail), and are ready to support review whenever a maintainer is available.