@imageupload/mcp

MCP (Model Context Protocol) server for imageupload.io - lets AI agents (Claude Desktop, Cursor, and any MCP-compatible client) upload images and get back share URLs with a single tool call.

Install / use

No global install needed. Every MCP client invokes this package via npx.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your OS:

{
  "mcpServers": {
    "imageupload": {
      "command": "npx",
      "args": ["-y", "@imageupload/mcp"],
      "env": {
        "IMAGEUPLOAD_API_KEY": "iu_live_YOUR_KEY_HERE"
      }
    }
  }
}

Get your API key from imageupload.io/dashboard/profile.

Cursor / other MCP clients

Configure an MCP server with:

• Command: npx
• Args: -y @imageupload/mcp
• Env: IMAGEUPLOAD_API_KEY=iu_live_...

Tools

| Tool | Description | |---|---| | upload_image | Upload an image. Accepts path (local file) or data_base64 + filename + mime. | | list_images | List every image you've uploaded. | | get_image | Get metadata for one image by slug. | | delete_image | Delete one of your images. |

upload_image arguments

| Key | Required | Description | |---|---|---| | path | one of | Local file path. MIME/filename are inferred. | | data_base64 | one of | Base64-encoded bytes. Requires filename and mime. | | filename | with data_base64 | Stored filename. | | mime | with data_base64 | One of image/png, image/jpeg, image/webp, image/gif, image/avif. | | expiration | no | 1d (default), 1w, 1mo, burn, views, or forever (Pro only). | | view_limit | when expiration=views | Integer 1–999. | | password | no | Gate the share page with a password. |

Returns a structuredContent object:

{
  "slug": "Ab3f9X2k",
  "share_url": "https://imageupload.io/i/Ab3f9X2k",
  "direct_url": "https://imageupload.io/f/Ab3f9X2k.png",
  "size": 14321,
  "width": 800,
  "height": 600,
  "expires_at": 1775000000
}

Self-hosted endpoint

Point to your own imageupload.io instance:

IMAGEUPLOAD_API_URL=https://images.example.com/mcp \
IMAGEUPLOAD_API_KEY=iu_live_... \
npx -y @imageupload/mcp

Troubleshooting

Run the server directly to see logs on stderr:

IMAGEUPLOAD_API_KEY=iu_live_... npx -y @imageupload/mcp

Then pipe a single initialize request in:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | IMAGEUPLOAD_API_KEY=iu_live_... npx -y @imageupload/mcp

License

MIT © imageupload.io