Feature request: Add attachment/image support to the MCP `send_message` tool

[omni-gh549]

Summary

The MCP server exposed at localhost:23373 (via @beeper/desktop-mcp) currently only supports sending plain text messages through the send_message tool. There is no way to send images or file attachments, which severely limits what AI assistants (e.g. Claude via Cowork/Claude Desktop) can do on behalf of users.

Current behaviour

The send_message tool signature only accepts a chatID and text parameter. Attempting to send an image requires falling back to UI automation workarounds, which are fragile and not a proper solution.

Requested feature

Add an optional attachment parameter (file path or URL) to the send_message MCP tool. The implementation could:

1. Accept a local file path or a remote URL as the attachment value
2. Upload the file to the Matrix media repository using the Matrix media upload API (/_matrix/media/v3/upload)
3. Construct and send an appropriate Matrix event - m.image for images, m.file for generic files - with the resulting mxc:// URI

Example proposed tool signature

{
  "name": "send_message",
  "parameters": {
    "chatID": "string",
    "text": "string (optional if attachment provided)",
    "attachment": "string (optional) - local file path or URL"
  }
}

Why this matters

AI assistants integrated via MCP are increasingly being used to help users manage their messages. The ability to send images and files is a fundamental part of modern messaging - without it, the MCP integration is limited to read and text-reply workflows only. This would unlock use cases like sharing screenshots, documents, and generated images directly through Beeper via AI.

Context

• Package: @beeper/desktop-mcp (this repo, packages/mcp-server)
• MCP server runs locally at localhost:23373
• Beeper is built on Matrix, so the media upload path is well-defined
• Raised by a user integrating Beeper MCP with Claude (Cowork mode)

[braklo]

+1, hitting the same gap. Filed as Beeper Support ticket DESK-25699 on 2026-04-13 — support replied "Thanks for the heads up! I've shared this with the team so they can take a look." but no public progress yet, so cross-linking here.

The REST workaround documented by @jrejaud in #35 is confirmed working in production. Concretely:

# 1. Upload
UPLOAD=$(curl -s -X POST "http://localhost:23373/v1/assets/upload" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/image.jpg;type=image/jpeg")
UPLOAD_ID=$(echo "$UPLOAD" | jq -r .uploadID)

# 2. Send with attachment
curl -s -X POST "http://localhost:23373/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"text\":\"caption\",\"attachment\":{\"uploadID\":\"$UPLOAD_ID\",\"mimeType\":\"image/jpeg\",\"fileName\":\"image.jpg\"}}"

POST /v1/assets/upload/base64 with { content, fileName, mimeType } works as an alternative when shelling out to multipart isn't available.

Native MCP send_message support for attachment (matching the REST shape) would let agents send images/files without dropping out of the MCP layer to raw HTTP, and would remove the silent text-only truncation that today happens with no warning to the caller.