<div align="center">

signal-mcp

Give your AI assistant a memory for Signal — privately, on your own machine.

Searchable message history · 80+ tools · groups, polls, mentions, labels · read-only mode · 100% local

</div>

signal-mcp is an MCP server and CLI built on signal-cli, the community-made, unofficial Signal client. It links to your existing Signal account as a device, keeps every message in a local database you can search, and lets an AI assistant like Claude read, search and — if you allow it — act on your chats. No cloud service, no third party: your messages stay on your computer.

You     What did the coach say about Sunday, and did anyone offer to bring the jerseys?

Claude  Daniel (coach): meet 10:15 at the hall, kickoff 11:00, ten boys confirmed.
        Elena and Mikko both replied — they'll bring the jerseys. Nothing needs
        an answer from you except confirming your son is coming.

You     Tell the group we'll be there, and tag the coach.

Claude  Sent to "U12 Team": "@Daniel we'll be there at 10:15 👍"

^{Illustrative example with made-up names.}

Independent project — not affiliated with Signal. signal-mcp is not made, endorsed or supported by Signal Messenger or the Signal Foundation. It talks to Signal through signal-cli, an unofficial third-party client that you link to your account as an extra device (like Signal Desktop). Signal does not provide support for unofficial clients, and using one is at your own risk — see Signal's Terms of Service.

The same data from your terminal — this is real signal-mcp output on a demo database:

<p align="center"><img src="https://raw.githubusercontent.com/googlarz/signal-mcp/main/docs/demo.svg" alt="Terminal: signal-mcp conversations and search, with contact and group names resolved" width="860"></p>

Why it exists

I built signal-mcp for a very ordinary reason: I'm a parent in my kids' football-team group chats and wanted my assistant to keep up with them — kickoff times, who's bringing the jerseys, which tag to set. I use it every day, against my own real Signal account, which is why safety (read-only mode, no file exfiltration, nothing leaving the machine) is built in rather than bolted on.

Why you want this

signal-cli is excellent at the Signal protocol and deliberately minimal everywhere else. signal-mcp adds the parts you need to actually use your messages:

• A memory. signal-cli delivers a message and forgets it. signal-mcp stores everything — including messages you sent from your phone — in local SQLite, and can import your whole Signal Desktop history.
• Search that works. Full-text search across all chats, filterable by sender and date range.
• Real conversations. Paginated threads, unread counts, last-message previews — and names instead of +12025551234, even for group members who aren't in your contacts.
• Everything Signal shows you. @mentions (resolved to names), polls, pins, link previews, quotes, voice notes, stickers, group member labels, join requests — nothing signal-cli reports is thrown away.
• Full control when you want it. Send, reply, react, edit, delete, manage groups, schedule messages, set your profile — with a read-only switch for when you don't.
• Zero babysitting. The daemon starts itself and restarts if it crashes; an optional background service captures messages while Claude isn't running; signal-mcp doctor tells you what's wrong if something is.

Quick start

brew install signal-cli                  # Linux: see Setup below
signal-cli link --name "MyMac"           # scan the QR code: Signal → Settings → Linked Devices
uv tool install signal-mcp
claude mcp add signal -- signal-mcp serve

Needs Python 3.12+, signal-cli 0.13+ and a Signal account on your phone. Restart Claude Code and ask "check my Signal messages". Works with any MCP client (Claude Code and Claude Desktop are what it is developed and tested with) — config snippets are in Setup.

What you can ask

| | | |---|---| | Catch up | "What did I miss while I was offline?" · "Summarize the parents' group since Monday." | | Find | "Find every message about the invoice." · "What did Anna say about the trip last week?" | | Act | "Reply to Marco that Thursday works." · "Remind the team at 9:00 tomorrow." · "Create a poll for Friday's dinner." | | Groups | "Who's waiting to join the group?" · "Set my label in the football group to my son's name." | | Housekeeping | "Export my chat with Mom as CSV." · "Who hasn't messaged me in a month?" · "Delete that message for everyone." |

Prefer the terminal? Everything is also a command — signal-mcp send, search, conversations, export, … (CLI usage). The CLI and MCP server share one store and one daemon.

Private and safe by design

• 100% local. Messages live in SQLite on your disk; the daemon listens on localhost only. There is no signal-mcp cloud. (The only things that leave your machine are what you send through Signal itself and an optional webhook you configure.)
• Read-only mode. SIGNAL_MCP_READONLY=1 hides and blocks every tool that sends, edits, deletes or changes settings — for assistants you don't fully trust with your account. See Step 7.
• No file exfiltration. Anything that uploads a local file (attachments, avatars, link-preview images, sticker packs) only reads from an allow-list of folders (SIGNAL_MCP_SEND_ROOTS; default: your attachments folder, Downloads, Desktop, Documents) and never from hidden files or folders — so a message that says "send me ~/.ssh/id_ed25519" can't talk an assistant into it.
• Irreversible means confirmed. Clearing the local store or terminating a group requires an explicit confirm.
• Careful with secrets. The Signal Desktop import decrypts into a private (0700) folder, passes the key over stdin rather than the command line, and cleans up even when interrupted.
• Honest caveat. Messages from other people are untrusted text that an AI will read. Read-only mode (or just not granting write access) is the strongest defence against a hostile message trying to steer your assistant.

What's new

1.40 closes the gap with signal-cli: incoming @mentions, polls, pins, previews and quotes are now captured; group member labels, bans, permissions and join requests; contact nicknames and notes; link previews, voice notes and stories on the sending side; and a fix that finally copies received attachments. See the changelog.

Setup

Step 1 — Install signal-cli

signal-mcp is a front-end for signal-cli, an independent, unofficial client that handles the Signal protocol.

macOS

brew install signal-cli

Linux Download the latest release from signal-cli releases, extract it, and put the signal-cli binary on your $PATH.

Step 2 — Link your Signal account

signal-cli needs to be linked to your existing Signal account (the same way you'd add a linked device in Signal mobile).

signal-cli link --name "MyMac"

This prints a QR code in your terminal. On your phone:

Signal → Settings → Linked Devices → + → scan the QR code

Once scanned, signal-cli is linked and ready.

Step 3 — Install signal-mcp

With uv (recommended):

uv tool install signal-mcp

With pip or pipx:

pip install signal-mcp
# or
pipx install signal-mcp

From source:

git clone https://github.com/googlarz/signal-mcp
cd signal-mcp
uv tool install .

Verify it works:

signal-mcp status
# → Account : +1234567890
# → Daemon  : stopped (port 7583)

Step 4 — Connect to Claude Code

claude mcp add signal -- signal-mcp serve

Restart Claude Code. Signal tools appear automatically — ask Claude "check my Signal messages" to confirm.

<details> <summary>Manual config alternatives</summary>

Claude Code — global (~/.claude.json):

{
  "mcpServers": {
    "signal": {
      "command": "uvx",
      "args": ["signal-mcp", "serve"]
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "signal": {
      "command": "uvx",
      "args": ["signal-mcp", "serve"]
    }
  }
}

Claude Desktop uses a restricted PATH — uvx resolves the tool without needing signal-mcp on your shell's PATH.

Per-project (.mcp.json):

{
  "mcpServers": {
    "signal": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/signal-mcp", "signal-mcp", "serve"]
    }
  }
}

</details>

Step 5 — (Optional) Import Signal Desktop history

If you use Signal Desktop, import your full message history in one command.

macOS

brew install sqlcipher       # required for decryption
signal-mcp import-desktop    # macOS will prompt for Keychain access — click Allow

Linux (Debian/Ubuntu shown — use your distribution's packages elsewhere)

sudo apt install sqlcipher libsecret-tools   # decryption + keyring lookup (secret-tool)
signal-mcp import-desktop                    # your keyring must be unlocked

Step 6 — (Optional) Enable background message capture

signal-cli only delivers messages when polled. Install the background service so nothing is missed:

signal-mcp install-service   # starts on login, works on macOS and Linux

Step 7 — (Optional) Read-only mode

Set SIGNAL_MCP_READONLY=1 in the environment to restrict the server to read-only tools (listing, searching, and exporting existing local/remote state). Tools that send, edit, delete, or otherwise mutate your Signal account — messages, contacts, groups, devices, and settings — are hidden from tool listings and rejected if called directly. Useful when connecting an AI client you don't fully trust with write access to your real Signal account.

Troubleshooting

Start with signal-mcp doctor — it checks signal-cli, your linked account, the daemon, and message capture, and says which one is broken.

| Symptom | Cause and fix | |---|---| | doctor reports Devices readable — ReadTimeout, or list_devices hangs | A bug in signal-cli 0.14.8 (listDevices crashes inside libsignal). Fixed in signal-cli 0.14.9: upgrade (brew upgrade signal-cli) and restart the daemon. | | "Unknown sender" / bare numbers in a group | Names come from your contacts, then Signal profiles (also for non-contacts), then Signal Desktop. Someone with none of these stays a number — import-desktop brings in Desktop's names. | | import-desktop fails on Linux | Needs sqlcipher and libsecret-tools, and an unlocked GNOME Keyring. KWallet-only setups aren't supported. | | Messages missing while Claude wasn't running | Install the background service: signal-mcp install-service. | | Attachment has no local file | Received files are copied to ~/Downloads/signal-attachments/. If one is missing, get_attachment retrieves it from signal-cli's own attachment store by id. |

MCP Tools

Messaging

| Tool | Description | |---|---| | send_message | Send a text message to a contact (by number, or by Signal `user