Skip to main content
Glama
googlarz

Signal MCP

by googlarz
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

send_attachment

Send one or more files (photos, videos, documents, audio) to one Signal contact in a single message. Use send_group_attachment for groups, send_message for text only, send_sticker for stickers.

Instructions

Send one or more files (photos, videos, documents, audio) to one Signal contact in a single message. Use send_group_attachment for groups, send_message for text only, send_sticker for stickers. Address by recipient (E.164) or username (alice.42 or username link) — exactly one. path: a single file; paths: several files sent together (one of the two is required). Files must lie inside the allowed send folders (default: the signal-mcp attachments folder, ~/Downloads, ~/Desktop, ~/Documents; override with SIGNAL_MCP_SEND_ROOTS) and not be hidden, else an error is returned. caption: text shown with the files (default empty); view_once=true lets the recipient open media only once; voice_note=true marks audio as a voice note. attachment_dimensions (WIDTHxHEIGHT per file, in order) and attachment_blurhash (BlurHash per file, in order) give clients a size and a preview before download; an empty string skips a file. Reply/quote: quote_author (E.164) + quote_timestamp (ms) of the original; quote_message (quoted text; default: looked up in the local store), quote_mentions ({start, length, author}), quote_text_styles ('start:length:STYLE') and quote_attachments ('contentType[:filename[:previewFile]]') only shape the quote bubble. no_urgent=true sends without a push notification; notify_self=true delivers a normal notifying message if you are among the recipients. Contacts Signal's servers; not idempotent (repeating sends a duplicate); sends share a 20-per-minute rate limit (calls wait rather than fail). Saved to the local store (caption as body). Returns {status, timestamp}.

Input Schema

NameRequiredDescriptionDefault
pathNoSingle file path (absolute, relative, or ~/path)
pathsNoMultiple file paths to send as one message
captionNoOptional caption text shown below the attachment
usernameNoSignal username (e.g. alice.42) or username link, instead of recipient
no_urgentNoSend without the urgent flag, so the recipient gets no push notification
recipientNoPhone number in E.164 format
view_onceNoSend as view-once media — recipient can only view it once before it disappears
voice_noteNoMark audio attachments as voice notes (played inline in Signal)
notify_selfNoIf you are among the recipients, deliver as a normal (notifying) message instead of a silent sync message
quote_authorNoPhone number (E.164) of the author of the message being quoted/replied to
quote_messageNoText of the quoted message shown in the quote bubble. Default: looked up in the local store by quote_author + quote_timestamp
quote_mentionsNo@mentions inside the quoted text, same shape as mentions: {start, length, author}
quote_timestampNoTimestamp of the message being quoted/replied to (from get_conversation)
quote_attachmentsNoAttachments of the quoted message as 'contentType[:filename[:previewFile]]', e.g. 'image/png:photo.png'
quote_text_stylesNoStyles inside the quoted text as 'start:length:STYLE' (BOLD, ITALIC, SPOILER, STRIKETHROUGH, MONOSPACE)
attachment_blurhashNoBlurHash per file, in file order, shown by clients while the file downloads; use '' to skip one
attachment_dimensionsNoDisplayed size per file, in file order, as 'WIDTHxHEIGHT' (e.g. '1080x1920'); use '' to skip one

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.43.1
    • addedInput schema / properties / attachment_blurhash
      Added value: +{
+  "description": "BlurHash per file, in file order, shown by clients while the file downloads; use '' to skip one",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • addedInput schema / properties / attachment_dimensions
      Added value: +{
+  "description": "Displayed size per file, in file order, as 'WIDTHxHEIGHT' (e.g. '1080x1920'); use '' to skip one",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
  2. Changed11 schema fields changedv1.40.1
    • addedInput schema / properties / no_urgent
      Added value: +{
+  "default": false,
+  "description": "Send without the urgent flag, so the recipient gets no push notification",
+  "type": "boolean"
+}
    • addedInput schema / properties / notify_self
      Added value: +{
+  "default": false,
+  "description": "If you are among the recipients, deliver as a normal (notifying) message instead of a silent sync message",
+  "type": "boolean"
+}
    • addedInput schema / properties / quote_attachments
      Added value: +{
+  "description": "Attachments of the quoted message as 'contentType[:filename[:previewFile]]', e.g. 'image/png:photo.png'",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • addedInput schema / properties / quote_author
      Added value: +{
+  "description": "Phone number (E.164) of the author of the message being quoted/replied to",
+  "type": "string"
+}
    • addedInput schema / properties / quote_mentions
      Added value: +{
+  "description": "@mentions inside the quoted text, same shape as mentions: {start, length, author}",
+  "items": {
+    "properties": {
+      "author": {
+        "type": "string"
+      },
+      "length": {
+        "type": "integer"
+      },
+      "start": {
+        "type": "integer"
+      }
+    },
+    "type": "object"
+  },
+  "type": "array"
+}
    • addedInput schema / properties / quote_message
      Added value: +{
+  "description": "Text of the quoted message shown in the quote bubble. Default: looked up in the local store by quote_author + quote_timestamp",
+  "type": "string"
+}
    • addedInput schema / properties / quote_text_styles
      Added value: +{
+  "description": "Styles inside the quoted text as 'start:length:STYLE' (BOLD, ITALIC, SPOILER, STRIKETHROUGH, MONOSPACE)",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • addedInput schema / properties / quote_timestamp
      Added value: +{
+  "description": "Timestamp of the message being quoted/replied to (from get_conversation)",
+  "type": "integer"
+}
    • addedInput schema / properties / username
      Added value: +{
+  "description": "Signal username (e.g. alice.42) or username link, instead of recipient",
+  "type": "string"
+}
    • addedInput schema / properties / voice_note
      Added value: +{
+  "default": false,
+  "description": "Mark audio attachments as voice notes (played inline in Signal)",
+  "type": "boolean"
+}
    • removedInput schema / required
      Removed value: -[
-  "recipient"
-]
  3. Changed3 schema fields changedv0.1.2
    • changedInput schema / properties / caption / description
      Previous value: -"Optional caption text"New value: +"Optional caption text shown below the attachment"
    • changedInput schema / properties / paths / description
      Previous value: -"Multiple file paths to send in one message"New value: +"Multiple file paths to send as one message"
    • changedInput schema / properties / view_once / description
      Previous value: -"Send as view-once (disappears after viewing)"New value: +"Send as view-once media — recipient can only view it once before it disappears"
  4. First observedv0.1.0

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover the safety profile (readOnly=false, openWorld=true, idempotent=false, destructive=false), and the description adds substantial context beyond them: the 20-per-minute rate limit with queuing behavior, non-idempotency with duplicate consequences, allowed-folder restrictions and hidden-file errors, the return shape {status, timestamp}, and the local-store save. This is rich disclosure on top of what annotations already provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and alternatives, then constraints, then optional nuance. It is dense and heavily parenthetical, which slightly impairs scanability, but nearly every clause carries operational information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 17-parameter mutation tool with no output schema, the description is remarkably complete: return value, rate limit, idempotency, path restrictions, error conditions, and the role of every optional group are all covered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline would be 3, but the description adds real meaning: path vs paths mutual exclusivity, positional ordering and empty-string skipping for attachment_dimensions/blurhash, and the clarification that quote_* fields only shape the quote bubble. These semantics are not derivable from the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource+scope: 'Send one or more files ... to one Signal contact in a single message.' It explicitly distinguishes itself from send_group_attachment, send_message, and send_sticker by name, so an agent can route without opening sibling schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the three sibling alternatives (send_group_attachment for groups, send_message for text, send_sticker for stickers) and states the addressing rule (exactly one of recipient/username) and the path/paths mutual requirement. Nothing about when-to-use is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools