BeeIMG MCP Server

BeeIMG exposes its image hosting API through the Model Context Protocol (MCP) so AI assistants, coding tools, and agents can upload, host, and delete images directly.

The endpoint speaks MCP v2 (protocol version 2026-07-28, Streamable HTTP transport) and automatically falls back to the legacy initialize-based protocol (2025-11-25 and earlier) for older clients.

Listed in the official MCP Registry as com.beeimg/mcp — registry-aware clients can find and connect to it by that name.

Endpoint

A single URL, used by every MCP client:

https://beeimg.com/mcp
  • Transport: Streamable HTTP — every JSON-RPC message is its own POST.
  • Replies are single JSON objects (application/json); no SSE streams are used by this server.
  • Protocol version 2026-07-28 requires the MCP-Protocol-Version, Mcp-Method, and (for tools/call) Mcp-Name headers on each request. MCP client SDKs send these automatically.
  • Clients that use initialize are served the legacy protocol automatically.

Connect an MCP client

Add to claude_desktop_config.json (Settings > Developer):

{
  "mcpServers": {
    "beeimg": {
      "url": "https://beeimg.com/mcp"
    }
  }
}

Add to ~/.cursor/mcp.json (Settings > MCP):

{
  "mcpServers": {
    "beeimg": {
      "url": "https://beeimg.com/mcp"
    }
  }
}

Add to opencode.json (project or global config):

{
  "mcp": {
    "beeimg": {
      "type": "remote",
      "url": "https://beeimg.com/mcp",
      "enabled": true
    }
  }
}

Agent skill (auto-setup for AI coding agents)

Install the beeimg-mcp Agent Skill to teach Claude Code, Cursor, opencode, or any skill-aware agent how to connect to and use this MCP server. 

# opencode: add to opencode.json
"skills": { "urls": ["https://beeimg.com/.well-known/skills/"] }

# other clients: copy skills/beeimg-mcp/ into your skill directory,
# or fetch the canonical file directly

Hosted for agent auto-discovery: https://beeimg.com/.well-known/skills/index.json (opencode index) and https://beeimg.com/.well-known/skills/beeimg-mcp/SKILL.md (skill body). In the beeimg repo, copy skills/beeimg-mcp/ from the skills/ directory — the canonical source is skills/beeimg-mcp/SKILL.md.

Local npm server (beeimg-mcp)

Prefer a local server? Install beeimg-mcp from npm — a stdio MCP server that calls the BeeIMG API directly (no hosted endpoint, free forever). It exposes the same eight tools. 

# stdio transport — use this command in any MCP client
npx beeimg-mcp

Point your client at the stdio command npx beeimg-mcp. Config examples and publish/directory-submission notes: internal/mcp/npm/README.md in the beeimg repo, or npmjs.com/package/beeimg-mcp.

Supported use cases (tools)

Tool What it does Key parameters
upload_url Fetch an image from a remote URL and host it on BeeIMG. url (required); apikey, albumid, privacy, title (optional)
upload_file Upload an image file (base64 or data URI) to BeeIMG. image (required); filename, apikey, albumid, privacy, title (optional)
delete_image Delete a hosted image by ID. image_id, apikey, delete_key (all required)
beeimg_premium_info Free-plan limits, premium perks, and upgrade links. Useful when an upload hits a rate/storage/size limit. — (no parameters)
list_albums List all albums owned by the authenticated user. apikey (required)
create_album Create a new album; returns the album ID for uploads. title, apikey (required); privacy (optional)
get_album Get album details, sub-folders, and contained images. id, apikey (required)
create_folder Create a sub-folder in an album; returns the 9-char folder ID. main_album_id, parent_id, apikey (required); name (optional)

Uploads return the hosted image URL, thumbnail URL, view page, and delete URL. Add albumid (a 5-char master album ID or 9-char folder ID) to file images into an album; see the Albums API for how to create albums and get folder IDs.

Authentication

  • Anonymous uploads work with no credentials — but deleting requires the delete_key returned at upload time.
  • Pass your API key as the apikey argument to upload_url / upload_file to attach images to albums.
  • delete_image takes apikey + delete_key together; uploads made with an apikey return "#" as a placeholder delete_key, so use your account dashboard or the delete URL for those.
  • API keys are created on the API key page.

Common errors & premium hints

When an upload fails, the server returns the raw API error plus a hint pointing at premium if it would help:

API code Meaning Premium hint
4File too largePremium raises the max file size
40Storage limit exceededPremium raises your storage limit
223Upload rate limit reachedPremium removes upload rate limits
503Uploader temporarily disabledPremium members get priority upload access

The full error-code list lives in the API docs.

Try it with curl

A modern (v2) request needs the three headers below; _meta carries the protocol version:

curl -sk https://beeimg.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: upload_url' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "upload_url",
      "arguments": {
        "url": "https://example.com/photo.jpg",
        "title": "My photo"
      },
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'
  • -k skips TLS verification — only needed for local/dev testing with self-signed certificates; drop it against the public endpoint.
  • Older MCP clients can skip the headers and just send an initialize request; the server falls back to the legacy protocol automatically.

More