signal-mcpl
Provides a Signal messaging integration that lets agents hold end-to-end-encrypted 1:1 conversations via signal-cli. It relays allowlisted inbound DMs to the agent, sends agent replies as Signal messages with native markdown formatting, and supports tools for sending messages, quoting, reacting, editing, deleting, fetching history, listing conversations, and optionally sending files. It also provides typing indicators and read receipts.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 carryingorigin.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 taggedchat: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, specifyto; 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_historyandchannels/openread 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_SENDERSare 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=manualand 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 runssignal-cli trust.send_fileis confined toSIGNAL_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 hijacks3. 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 | |
| — (required) | The bot's registered number (or ACI). |
| empty ⇒ relay nothing | Comma-separated numbers and/or ACIs. |
| — |
|
|
| Executable for spawn mode. |
| signal-cli default | signal-cli data dir ( |
| — | Use a running daemon instead of spawning. |
|
| Message log and contact book. |
| on |
|
| on |
|
| — (tool hidden) | Colon-separated dirs |
| 3500000 | Larger images are described, not inlined. |
| 65536 | Larger text files are described, not inlined. |
| system | Injected by connectome-host; used in |
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, pluschat:reply(quoting the agent) andchat:has-image|audio|file. Edits, deletes, and reactions carry onlychat:private,chat:from-human, andchat:edited/chat:deleted/chat:reaction/chat:reaction-remove— neverchat:dm, because the host expandschat:dmtochat:addressed(MCPL §16.3).
Development
npm test # unit tests + an end-to-end run against a fake signal-clisrc/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
Social media, DMs, blog syndication & E.164 telecom for AI agents across 18+ networks.
The communications layer for AI agents: posts, DMs, team rooms, and file exchange.
SwarmDM (formerly AgoraDM): DMs, friends, groups and files between AI agents.
End-to-end encrypted messaging and work coordination for autonomous AI agents.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables LLM agents to send, receive, and discover contacts on the agentic message bus via native tools.5MIT
- AlicenseNot gradedqualityCmaintenanceEnables an AI agent to interact with your personal Telegram direct messages, allowing it to read unread messages, fetch chat history, and send replies.MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseNot gradedqualityCmaintenanceEnables 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