mcp-image-adapter

MCP Image Adapter

A library for converting images to base64 format for use with Model Context Protocol (MCP) in Cursor AI and other MCP-compatible applications.

About

MCP Image Adapter is primarily designed for use with Cursor AI as an MCP server for image handling. It allows AI assistants to view and process images within the IDE, enhancing their contextual understanding and capabilities when working with visual content.

This adapter implements the Model Context Protocol (MCP), making it compatible with Cursor AI and other MCP-supporting applications.

Usage

This package is designed to be used as an MCP server with Cursor AI, not as a regular npm dependency. To use it, configure Cursor AI as described in the "Cursor Configuration" section below.

Compatibility

• Tested and works well with Claude 3.7.
• Known Issue: There is an incompatibility with the argument schema for the mcp_image-adapter_get_compressed_image tool when used with gemini-2.5-pro-preview-05-06. This may lead to errors when this specific tool is invoked by that model.

Available Tools

For Working with Original Images

• get_unprocessed_image - get original image in base64 format without compression
• get_multiple_unprocessed_images - get multiple original images without compression

For Working with Compressed Images

• get_compressed_image - get compressed image
• get_multiple_compressed_images - get multiple compressed images

Additional Tools

• get_supported_formats - list of supported formats
• get_image_metadata - get image metadata

Cursor Configuration

To use mcp-image-adapter with Cursor AI, you need to create an MCP configuration file. Here's an example:

Project-Specific Configuration

Create a .cursor/mcp.json file in your project directory:

{
  "mcpServers": {
    "image-adapter": {
      "command": "npx",
      "args": ["-y", "mcp-image-adapter"]
    }
  }
}

Global Configuration

Alternatively, create a ~/.cursor/mcp.json file to make the adapter available across all projects:

{
  "mcpServers": {
    "image-adapter": {
      "command": "npx",
      "args": ["-y", "mcp-image-adapter"]
    }
  }
}

Once configured, Cursor AI will be able to use the image processing tools provided by the adapter.

Tips

Optimizing Image Tools Usage

For most use cases, we recommend using compressed image methods instead of unprocessed ones. In your Cursor configuration (.cursor/rules or .cursorrules), you can set up tool preferences to prioritize compressed image methods.

Using compressed images has several advantages:

• Reduces context token consumption
• Improves processing speed
• Still provides sufficient visual information for AI models

Roadmap

Brief overview of our future plans:

• Testing: Expand test coverage, add integration tests
• Security: Implement path validation, file size limits, and safer MIME type handling
• Logging: Add structured logging with configurable verbosity levels

License

MIT