Skip to main content
Glama
signal-mcpl

signal-mcpl

by jimmielin

connectome-signal-mcpl

A Signal surface for Connectome agents. It is an MCPL server that wraps signal-cli's JSON-RPC interface, so an agent can hold end-to-end-encrypted 1:1 conversations from any Signal client (Signal, Molly, …).

phone (Signal/Molly) ⇄ Signal service ⇄ signal-cli ⇄ signal-mcpl ⇄ connectome-host ⇄ agent
                     └──────── end-to-end encrypted ────────┘

Messages are encrypted between the phone and the host running signal-cli; the Signal service never sees plaintext. (The agent's inference provider and the host's disk necessarily do.)

What it does

  • Inbound: DMs from allowlisted contacts are delivered to the agent as push/events carrying origin.mcplChannelId (signal:dm:<ACI>), so the host registers the conversation and routes the agent's prose reply straight back. Edits, deletes, and reactions are relayed too (not tagged chat:addressed, so wake policies can treat them as ambient). Images are inlined; small text files are inlined; voice notes and other files are described.

  • Outbound: the agent's prose (channels/publish) is sent as a Signal message, with markdown converted to Signal's native formatting (bold, italic, strikethrough, monospace, spoiler). Long messages are handled by signal-cli.

  • Presence: a typing indicator while the agent is responding, and read receipts once the agent actually engages (types, replies, or reacts), not merely when the host queues the message.

  • Tools: send_message (incl. quoting), react, edit_message, delete_message, fetch_history, list_conversations, and — if enabled — send_file. With multiple known contacts, specify to; ambiguous names are refused, so use the channel ID when names overlap.

  • History: Signal has no server-side history, so every relayed message is appended to $SIGNAL_STATE_DIR/messages.jsonl; fetch_history and channels/open read from it.

Not yet: group chats (ignored), voice-note transcription, MCPL rollback.

Related MCP server: social-mcp

Safety properties

  • Allowlist, fail-closed. Only senders in SIGNAL_ALLOWED_SENDERS are relayed, and the agent can only message allowlisted contacts. An empty list relays nothing. Dropped senders are logged by id only, never by content.

  • Nothing is lost before the host is ready. signal-cli runs with --receive-mode=manual and is only subscribed once the host has granted push delivery (MCPL §5.3), so the Signal service holds messages until then.

  • Safety-number changes are not auto-trusted (signal-cli's default on-first-use). A send to a contact whose key changed fails with an explanatory error until an operator verifies and runs signal-cli trust.

  • send_file is confined to SIGNAL_SEND_FILE_ROOTS (symlinks resolved); without that variable the tool is not offered at all.

Setup

1. Install signal-cli

macOS: brew install signal-cli. Linux: download a release from https://github.com/AsamK/signal-cli/releases (the native build needs no JVM; the JVM build needs the Java version named in the release notes). Keep it updated — Signal stops accepting old clients after a few months. The JSON-RPC integration was reviewed against signal-cli 0.14.9.

2. Register the bot's number

Run these as the user that will run the agent (signal-cli keeps its keys in ~/.local/share/signal-cli unless --config says otherwise):

# Solve https://signalcaptchas.org/registration/generate.html and copy the
# "Open Signal" link (signalcaptcha://…).
signal-cli -a +1BOTNUMBER register --captcha 'signalcaptcha://…'
#   landline? after one SMS attempt: add --voice
signal-cli -a +1BOTNUMBER verify 123456

signal-cli -a +1BOTNUMBER updateProfile --given-name SignalBot   # optional: --avatar pic.png
signal-cli -a +1BOTNUMBER setPin 'a-long-registration-lock-pin'   # blocks re-registration hijacks

3. Find your own id

From your phone, send the bot a message. Then run the server (or the agent) with your number in SIGNAL_ALLOWED_SENDERS. If your number is hidden by Signal's phone-number privacy, the message is dropped and the log prints your ACI instead:

[signal-mcpl] dropped message from non-allowlisted sender uuid=… number=-

Put that UUID in SIGNAL_ALLOWED_SENDERS.

4. Build and add to the recipe

Requires Node.js 22.12 or newer.

git clone https://github.com/jimmielin/connectome-signal-mcpl.git
cd connectome-signal-mcpl
npm install && npm run build
"mcpServers": {
  "signal": {
    "command": "node",
    "args": ["/path/to/connectome-signal-mcpl/dist/src/index.js", "--stdio"],
    "env": {
      "SIGNAL_ACCOUNT": "${SIGNAL_ACCOUNT}",
      "SIGNAL_ALLOWED_SENDERS": "${SIGNAL_ALLOWED_SENDERS}",
      "SIGNAL_CONTACT_NAMES": "${SIGNAL_CONTACT_NAMES}",
      "SIGNAL_STATE_DIR": "./data/signal",
      "SIGNAL_CLI_BIN": "/path/to/signal-cli"
    }
  }
}

and, if the recipe has explicit wake policies, wake on addressed Signal messages while letting reactions/edits wait for the next turn:

"wake": { "policies": [
  { "name": "signal-dm", "match": { "source": "signal", "tagsAny": ["chat:addressed"] }, "behavior": "always" },
  { "name": "signal-ambient", "match": { "source": "signal" }, "behavior": "defer" }
] }

(source is the mcpServers key.)

Set SIGNAL_ACCOUNT and SIGNAL_ALLOWED_SENDERS in the host's environment before loading this recipe. Set SIGNAL_CONTACT_NAMES too, or remove its optional line: Connectome rejects substitutions for unset variables. Other SIGNAL_* settings must also be passed explicitly in the server's env map; the host does not inherit arbitrary environment variables into MCPL children.

Running signal-cli as a separate daemon (optional)

By default signal-mcpl spawns signal-cli as a child process. To keep signal-cli running across agent restarts instead, run it as a service and point the server at its socket:

signal-cli -a +1BOTNUMBER daemon --socket /run/user/$UID/signal-cli.sock --receive-mode=manual
"SIGNAL_CLI_SOCKET": "/run/user/1000/signal-cli.sock"

Socket requests explicitly select SIGNAL_ACCOUNT, and notifications for other accounts are ignored. In socket mode, use the phone number for a numbered account, or the ACI for a numberless account, matching signal-cli's notification account field.

Configuration

Variable

Default

SIGNAL_ACCOUNT

— (required)

The bot's registered number (or ACI).

SIGNAL_ALLOWED_SENDERS

empty ⇒ relay nothing

Comma-separated numbers and/or ACIs.

SIGNAL_CONTACT_NAMES

—

id=Name,… display names shown to the agent.

SIGNAL_CLI_BIN

signal-cli

Executable for spawn mode.

SIGNAL_CLI_CONFIG

signal-cli default

signal-cli data dir (--config).

SIGNAL_CLI_SOCKET

—

Use a running daemon instead of spawning.

SIGNAL_STATE_DIR

./signal-state

Message log and contact book.

SIGNAL_MARKDOWN

on

off sends agent text verbatim.

SIGNAL_READ_RECEIPTS

on

off never sends read receipts.

SIGNAL_SEND_FILE_ROOTS

— (tool hidden)

Colon-separated dirs send_file may read.

SIGNAL_IMAGE_INLINE_MAX_BYTES

3500000

Larger images are described, not inlined.

SIGNAL_TEXT_INLINE_MAX_BYTES

65536

Larger text files are described, not inlined.

AGENT_TIMEZONE

system

Injected by connectome-host; used in fetch_history.

Local data and privacy

The state directory contains plaintext message content and contact IDs. New state directories are owner-only and state files are readable/writable only by their owner. Keep this directory and signal-cli's key/attachment directory out of Git, backups you do not trust, and public release artifacts. The npm package includes only the runtime, source, README, and license.

The append-only log retains original text even after a message is edited or deleted, and it does not implement Signal disappearing-message expiration. Only the most recent 5,000 log entries are loaded for history; the on-disk log is not automatically pruned. Delivery failures are logged, but are not automatically replayed after a server restart. Dropped-sender diagnostics contain contact IDs, and signal-cli's own diagnostics may also contain operational metadata. Treat stderr logs as private.

MCPL surface

  • Capabilities: pushEvents, channels.{register,lifecycle,publish,incoming,acknowledge,typing}.

  • Feature sets: signal.messaging (tools, pushEvents, channels.register, channels.publish) — the core; signal.channels (channels.lifecycle, channels.incoming, channels.acknowledge, channels.typing) — optional, so a host that withholds these degrades to "DMs in, replies out".

  • Event tags: messages carry chat:dm, chat:addressed, chat:private, chat:from-human, plus chat:reply (quoting the agent) and chat:has-image|audio|file. Edits, deletes, and reactions carry only chat:private, chat:from-human, and chat:edited / chat:deleted / chat:reaction / chat:reaction-remove — never chat:dm, because the host expands chat:dm to chat:addressed (MCPL §16.3).

Development

npm test    # unit tests + an end-to-end run against a fake signal-cli

src/mcpl05.ts and src/timezone.ts are vendored from connectome-heartbeat-mcpl; keep them in sync.

This MCPL was developed in collaboration with Claude Opus 5.5.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables LLM agents to send, receive, and discover contacts on the agentic message bus via native tools.
      5
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables an AI agent to interact with your personal Telegram direct messages, allowing it to read unread messages, fetch chat history, and send replies.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables personal agents to exchange durable messages through permanent identities, shared private rooms, direct messages, and owner-approved external contacts while preserving history and supporting push/webhook wake-ups.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables independently operated AI clients to exchange private 1:1 messages and files using authenticated participant identities, with retry deduplication, status tracking, notifications, and owner conversation inspection. Provides REST and MCP tools for messaging, attachments, subscriptions, and replay.
      MIT