Local Image Reader

PyPI version License: MIT

A simple Model Context Protocol (MCP) server that reads local images and returns them as ImageContent for LLM vision analysis.

Install in VS Code Install in VS Code Insiders

Features

• 📷 Read local images and return as base64-encoded ImageContent
• 🔧 Single tool: read_image - simple and focused
• 🚀 One-click installation for VS Code
• 📦 Install via PyPI with uvx - no environment setup needed

Supported Formats

PNG, JPEG, GIF, WebP, BMP, SVG

Installation

VS Code (Recommended)

Click the button above, or manually add to your VS Code settings:

For a specific version (recommended for security):

{
  "mcp": {
    "servers": {
      "local-image-reader": {
        "command": "uvx",
        "args": ["mcp-local-image-reader==0.1.1"],
        "env": {
          "UV_LINK_MODE": "copy"
        }
      }
    }
  }
}

For the latest version:

{
  "mcp": {
    "servers": {
      "local-image-reader": {
        "command": "uvx",
        "args": ["mcp-local-image-reader"],
        "env": {
          "UV_LINK_MODE": "copy"
        }
      }
    }
  }
}

Note: The UV_LINK_MODE=copy environment variable is required on Windows when using OneDrive or other cloud-synced folders.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "local-image-reader": {
      "command": "uvx",
      "args": ["mcp-local-image-reader==0.1.1"],
      "env": {
        "UV_LINK_MODE": "copy"
      }
    }
  }
}

Usage

In your AI assistant, ask it to read an image:

Please read the image at C:\Users\me\Pictures\screenshot.png and describe what you see.

The assistant will use the read_image tool to load the image and analyze it.

Security

Version Pinning

For production use, always pin to a specific version:

"args": ["mcp-local-image-reader==0.1.1"]

This ensures you won't automatically pull potentially malicious updates.

Source Code

This project is intentionally minimal (~100 lines) for easy auditing. The entire implementation is in server.py.

Known Issues

⚠️ Gemini Does Not Recognize Images from MCP

When using VS Code Copilot with Gemini models, images returned via MCP ImageContent are not visually recognized. The tool execution succeeds, but Gemini cannot "see" the image content.

Model	MCP Image Recognition
Claude	✅ Works
GPT	✅ Works
Gemini	❌ Not working

Root Cause: This is a known issue with how Gemini handles non-text content types in MCP responses.

Related Issue: gemini-cli #15851 - Only text content type supported

Workaround: Use Claude or GPT models for image analysis tasks until this issue is resolved.

Tool Reference

read_image

Reads an image from the filesystem and returns it as base64-encoded ImageContent.

Parameters:

• file_path (string, required): Absolute path to the image file

Returns:

• ImageContent with base64-encoded image data and appropriate MIME type

Example:

{
  "name": "read_image",
  "arguments": {
    "file_path": "/path/to/image.png"
  }
}

Development

# Clone the repository
git clone https://github.com/masachika-kamada/mcp-local-image-reader.git
cd mcp-local-image-reader

# Install dependencies
uv sync

# Run locally
uv run python server.py

# Test with MCP Inspector
npx @modelcontextprotocol/inspector uv run python server.py

License

MIT License - see LICENSE for details.

Contributing

Issues and pull requests are welcome! Please feel free to contribute.

Related Projects

• moiri-gamboni/image-reader-mcp - TypeScript implementation with directory listing
• k2sebeom/image-reader-mcp - Python implementation with remote URL support and image resizing