image-reader

This MCP server implements a lightweight image reader toolset built on FastMCP. It exposes two tools: list_images, which scans a given directory and returns the image filenames present, and read_image, which reads a specific image file and returns its content encoded in a way suitable for display (base64 via the imageContent helper in fastmcp). To use these tools, configure the imageReader server in your MCP client (as shown in the setup example) and invoke list_images with a directoryPath pointing to the directory containing images (supported extensions include .jpg, .jpeg, .png, .gif, .bmp, .webp, .svg). If you need to retrieve a specific image, call read_image with the filePath to the image; the response will include the image content ready for rendering in a client that supports the fastmcp imageContent format. Note that not all environments expose vision features equally; the repository’s notes indicate optimal compatibility with Claude Sonnet when used with Cursor integration, so expect best results there.

Prerequisites:

• Node.js v14+ and npm (for using npx to run the MCP server)
• Internet access to fetch the image-reader-mcp package via npm

Installation steps:

1. Verify prerequisites: node -v npm -v

2. Run the MCP server using npx (no local installation required): npx image-reader-mcp

   This uses the npm package image-reader-mcp to start the MCP server. If you want to configure it through your MCP client, you can reference the example in the README:

   { "mcpServers": { "imageReader": { "command": "npx", "args": ["image-reader-mcp"], "env": {} } } }

3. If you prefer to install a local copy for repeated runs, you can install the package locally and run it via node, depending on the package’s available entry point. For example: npm install image-reader-mcp npx image-reader-mcp

4. Verify runtime options and environment: Ensure the server has access to the directories you intend to scan for images and that file paths are absolute when using list_images and read_image.

5. Optional: integrate with Cursor or your MCP client as shown in the setup example, ensuring the imageReader entry is present under mcpServers.

Tips and caveats:

• Supported image extensions are .jpg, .jpeg, .png, .gif, .bmp, .webp, .svg. Ensure your directory contents match these extensions to be listed by list_images.
• The read_image tool returns content suitable for display via the imageContent helper in fastmcp; ensure your client can render base64-encoded image data.
• When using this server with Cursor, compatibility is best when Claude Sonnet is selected, as other models may not have vision features enabled.
• The environment (env) block is currently empty in the example; you can add variables as needed (e.g., TARGET_DIRECTORY, or API keys if you extend functionality).
• If you encounter path resolution issues, prefer absolute paths for directoryPath and filePath parameters to avoid working directory differences between the MCP server and client.
• If you plan to deploy in containers, you can wrap the npx invocation in a small wrapper script that validates inputs before forwarding to the MCP server.