Repository navigation
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.media-ctrl commentedon Nov 5, 2026
Techsynx commentedon Nov 5, 2026
Thanks @media-ctrl for the thorough verification and numbers! The 93x payload disparity (22.5 KB raw scanlines vs. 242 B compressed PNG) and the breakdown of why
tobytes()breaks round-trip decoding illustrate the defect clearly.I also strongly agree with the asymmetric cost rationale for keeping and fixing the snippet rather than deleting it. Documentation and snippet samples are often copied directly into downstream MCP servers, where an undecodable blob manifests as a cryptic client-side decode error with no server stack trace.
Your point about
img.formatis spot on as well—sinceimg.formatevaluates toNoneon synthetic/in-memory images and after transformations likethumbnail(), explicitly passingformat="PNG"toimg.save(buffer, format="PNG")and matchingformat="png"ensures the byte stream and the MIME label never drift.This is exactly the pattern implemented in PR #3809 (which also adds an integration test verifying the round-trip decoding and dimensions via PIL). Once a maintainer has capacity to review and assign the issue, the PR will reopen automatically and we'll be glad to shepherd it through.
fix(examples): encode thumbnail as PNG bytes instead of raw pixel data (