send_group_attachment
Send files such as photos, videos, documents, or audio to a Signal group in a single encrypted message. Supports view-once media and optional caption.
Instructions
Send one or more files (photos, videos, documents, audio) to a Signal group in a single message. All current group members receive the attachment via the normal Signal encrypted delivery pipeline. Provide path for a single file or paths for multiple files sent together in one message. Set view_once=true so each member can only open the media once before it disappears — ideal for sensitive images; does not apply to document types. The file must exist and be readable on the local filesystem; non-existent paths return an error. Use list_groups to obtain the group_id. Use when sharing a file with a group chat. Do NOT use for direct messages — use send_attachment instead. Do NOT use when you only want to send text — use send_group_message instead.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| group_id | Yes | Group ID (get from list_groups) | |
| path | No | Single file path (absolute, relative, or ~/path) | |
| paths | No | Multiple file paths to send as one message | |
| caption | No | Optional caption text shown below the attachment | |
| view_once | No | Send as view-once media — each recipient can only view it once |
Implementation Reference
- src/signal_mcp/client.py:361-386 (handler)The `send_group_attachment` method on SignalClient — the core handler that sends one or more files to a Signal group via JSON-RPC. Accepts group_id, path(s), optional caption, and view_once flag. Resolves file paths, builds params with groupId+attachment, calls the 'send' RPC method, and persists the sent message to the local store.
async def send_group_attachment( self, group_id: str, path: str | list[str], caption: str = "", view_once: bool = False, ) -> SendResult: await self._rate_limiter.acquire() paths = [path] if isinstance(path, str) else path resolved = [str(Path(p).expanduser().resolve()) for p in paths] params: dict = {"groupId": group_id, "attachment": resolved} if caption: params["message"] = caption if view_once: params["viewOnce"] = True result = await self._rpc("send", params) ts = result.get("timestamp", int(time.time() * 1000)) await asyncio.to_thread(_store.save_message, Message( id=f"sent_{ts}_{group_id}", sender=self.account, body=caption, timestamp=datetime.fromtimestamp(ts / 1000), group_id=group_id, is_read=True, # sent by us, already "read" )) return SendResult(timestamp=ts, recipient=group_id, success=True) - src/signal_mcp/server.py:236-261 (schema)The MCP Tool definition for 'send_group_attachment', including its description and inputSchema with properties: group_id (required), path, paths, caption, view_once.
Tool( name="send_group_attachment", description=( "Send one or more files (photos, videos, documents, audio) to a Signal group in a single message. " "All current group members receive the attachment via the normal Signal encrypted delivery pipeline. " "Provide path for a single file or paths for multiple files sent together in one message. " "Set view_once=true so each member can only open the media once before it disappears — " "ideal for sensitive images; does not apply to document types. " "The file must exist and be readable on the local filesystem; non-existent paths return an error. " "Use list_groups to obtain the group_id. " "Use when sharing a file with a group chat. " "Do NOT use for direct messages — use send_attachment instead. " "Do NOT use when you only want to send text — use send_group_message instead." ), inputSchema={ "type": "object", "properties": { "group_id": {"type": "string", "description": "Group ID (get from list_groups)"}, "path": {"type": "string", "description": "Single file path (absolute, relative, or ~/path)"}, "paths": {"type": "array", "items": {"type": "string"}, "description": "Multiple file paths to send as one message"}, "caption": {"type": "string", "description": "Optional caption text shown below the attachment", "default": ""}, "view_once": {"type": "boolean", "description": "Send as view-once media — each recipient can only view it once", "default": False}, }, "required": ["group_id"], }, ), - src/signal_mcp/server.py:1295-1305 (registration)The call_tool handler branch for 'send_group_attachment' — extracts path_arg, validates required group_id, calls client.send_group_attachment, and returns JSON result.
elif name == "send_group_attachment": path_arg = arguments.get("paths") or arguments.get("path") if not path_arg: return _err("Either path or paths is required") result = await client.send_group_attachment( arguments["group_id"], path_arg, caption=arguments.get("caption", ""), view_once=arguments.get("view_once", False), ) return _ok({"status": "sent", "timestamp": result.timestamp}) - src/signal_mcp/server.py:1118-1118 (registration)Required parameter validation entry for 'send_group_attachment' — specifies that 'group_id' is required.
"send_group_attachment":["group_id"], - src/signal_mcp/models.py:137-143 (helper)The SendResult dataclass returned by send_group_attachment (and other send methods), containing timestamp, recipient, success, and error fields.
@dataclass class SendResult: timestamp: int recipient: str success: bool error: str | None = None