Skip to main content
Glama
masachika-kamada

mcp-local-image-reader

by masachika-kamada
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

MCP 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

Related MCP server: kimi-read-image-mcp

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

Available Tools

1 tool
read_imageA

Read an image from the filesystem and return it as base64-encoded ImageContent. Supported formats: PNG, JPEG, GIF, WebP

ParametersJSON Schema
NameRequiredDescriptionDefault
file_pathYesAbsolute path to the image file

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses that the tool reads from the filesystem, returns base64 ImageContent, and supports specific formats. It does not mention error handling (e.g., file not found, unsupported format) or permissions, but for a simple read operation, the disclosure is fairly comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core action. Every sentence adds value: the first explains what it does and output format, the second lists supported formats. No redundant or verbose language.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema, no annotations, no siblings), the description is adequate. It covers purpose, input, output format, and supported types. It could mention that the operation is read-only and safe, but overall it is complete enough for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already describes the 'file_path' parameter as 'Absolute path to the image file'. The description does not add new meaning beyond this, so it meets the baseline of 3 for 100% schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Read', the resource 'image from the filesystem', and the output 'base64-encoded ImageContent'. It lists supported formats, making the purpose unambiguous. No sibling tools exist, so differentiation is not needed.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when needing to read an image as base64, but it does not provide explicit guidance on when to use this tool versus alternatives, or any prerequisites or exclusions. No siblings exist, so the lack of alternatives is not a penalty, but the description could still benefit from stating typical use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev0.1.1
    • First observedread_image
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
Disambiguation5/5

With only one tool, there is no risk of ambiguity or confusion for an agent.

Naming Consistency5/5

The single tool name 'read_image' follows a clear verb_noun pattern and is consistent within itself.

Tool Count4/5

A single tool is slightly thin, but for a specialized image reading server, it is well-scoped and appropriate.

Completeness3/5

The tool covers the core functionality of reading images, but lacks auxiliary capabilities like listing available images or checking file existence.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • llm-vision-mcp

    ghbalf
    A
    license
    Not graded
    quality
    C
    maintenance
    An MCP server that enables any LLM to describe images from file paths, URLs, or base64 data by forwarding them to a supported vision provider such as OpenAI, Anthropic, or local Ollama models.
    1,060
    10
    MIT

  • openai-image-mcp

    rammc
    A
    license
    Not graded
    quality
    C
    maintenance
    A minimal MCP server for generating images via OpenAI's GPT image model, supporting inline display or file output.
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/masachika-kamada/mcp-local-image-reader'

If you have feedback or need assistance with the MCP directory API, please join our Discord server