signal-mcp 1.11.0

Complete Signal MCP server and CLI via signal-cli

signal-mcp

The most complete Signal MCP server and CLI. Let Claude send and receive Signal messages, manage contacts and groups, search history, and more — all running 100% locally via signal-cli.

What Claude can do

Once connected, just ask Claude naturally:

"Check my Signal messages and summarize what I missed" "Send Anna a message saying I'll be 10 minutes late" "Reply to Marco's last message and quote what he said" "Search my Signal history for anything about the project deadline" "Show me all my conversations and who messaged me most recently" "Create a group with Alice and Bob called 'Weekend plans'" "Save a note to myself: pick up dry cleaning Thursday" "Import all my old messages from Signal Desktop"

Features

• 62 MCP tools — complete coverage of everything signal-cli exposes
• Quoted replies & @mentions — reply to specific messages, mention group members
• Edit & delete messages — fix typos, unsend mistakes
• View-once attachments — send photos that disappear after viewing
• Complete conversation history — sent and received messages stored locally in SQLite
• Full-text search — FTS5 index across all messages
• Signal Desktop import — pull your entire message history in one command (macOS)
• Background service — macOS LaunchAgent or Linux systemd unit captures messages automatically
• Full CLI — use Signal from your terminal without Claude
• 100% local — no cloud, no third-party services, your data stays on your machine
• Auto-starts daemon — no manual process management needed

Setup

Step 1 — Install signal-cli

signal-mcp is a front-end for signal-cli, which 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 : [phone]
# → 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.

Manual config alternatives

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"]
    }
  }
}

Step 5 — (Optional) Import Signal Desktop history

If you use Signal Desktop on macOS, import your full message history in one command:

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

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

MCP Tools

Messaging

Tool	Description
send_message	Send a text message to a contact. Supports quoted replies (quote_author, quote_timestamp).
send_group_message	Send a text message to a group. Supports quoted replies and @mentions.
send_attachment	Send a file or image to a contact. Supports captions and view-once.
send_group_attachment	Send a file or image to a group. Supports captions and view-once.
send_note_to_self	Save a note to yourself (Signal's saved messages).
receive_messages	Poll for new incoming messages and delivery receipts.
get_unread	Get messages not yet marked as read from local store.
edit_message	Edit a previously sent message (DM or group). Updates local store.
delete_message	Remote-delete (unsend) a sent DM.
delete_group_message	Remote-delete a sent group message.
react_to_message	React to a message with an emoji (DM or group). Set remove=true to unreact.
pin_message	Pin a message in a DM or group conversation.
unpin_message	Unpin a message in a DM or group conversation.
admin_delete_message	Group admin: delete any message in a group you administer.
set_typing	Send a typing indicator to a contact.
send_read_receipt	Mark messages as read. Also updates local store.
send_sticker	Send a sticker to a contact.
send_group_sticker	Send a sticker to a group.

Configuration

Tool	Description
get_configuration	Read current account settings (read receipts, typing indicators, link previews).
update_configuration	Toggle read receipts, typing indicators, link previews, or sealed sender indicators.

Sticker Packs

Tool	Description
list_sticker_packs	List all installed sticker packs with pack_id and sticker IDs for send_sticker.
add_sticker_pack	Install a sticker pack from a signal.art URL.

Contacts

Tool	Description
list_contacts	All contacts with names and numbers. Supports optional search filter.
get_profile	Get profile info for a contact.
update_contact	Set a local display name for a contact.
block_contact	Block a contact.
unblock_contact	Unblock a contact.
remove_contact	Remove a contact from the local list.
update_profile	Update your own name, about text, or avatar.
get_own_number	Get the Signal number this server is running as.

Groups

Tool	Description
list_groups	All groups with members and metadata.
create_group	Create a new Signal group.
join_group	Join a group via invite link.
update_group	Rename, add/remove members, promote/demote admins, set expiry timer.
leave_group	Leave a group.

History & Search

Tool	Description
list_conversations	All conversations ordered by most recent message.
get_conversation	Message history with a contact or group. Supports since, limit, and offset for pagination.
search_messages	Full-text search (FTS5) across all stored messages. Supports sender, limit, and offset.
store_stats	Total message count, oldest and newest message dates.
mark_as_unread	Mark one or more stored messages as unread.
get_user_status	Check whether phone numbers are registered Signal users.
send_sync_request	Request sync of messages/contacts/groups from your primary device.
send_contacts_sync	Push your contacts list to all linked devices.
send_message_request_response	Accept or decline a message request from an unknown sender.

Security & Devices

Tool	Description
list_identities	List identity keys and trust levels (safety numbers).
trust_identity	Trust a contact's identity key after verifying their safety number.
list_devices	List all devices linked to your account.
add_device	Link a new device using a device link URI.
remove_device	Unlink a device by ID.
update_device	Rename a linked device.
get_avatar	Retrieve the avatar image for a contact or group as base64.

Polls

Tool	Description
create_poll	Create a poll in a group conversation.
vote_poll	Cast a vote on an existing poll.
terminate_poll	End a poll and prevent further votes.

Disappearing Messages

Tool	Description
set_expiration_timer	Set or disable disappearing messages for any DM or group.

Data & Import

Tool	Description
import_desktop	Import full message history from Signal Desktop (macOS/Linux/Windows). Requires sqlcipher.
list_attachments	List all locally downloaded attachments (photos, files received via Signal).
get_attachment	Get details about a specific downloaded attachment by filename.
clear_local_store	Delete ALL locally stored messages (requires confirm: true). Does not unsend from Signal.
delete_local_messages	Delete locally stored messages for one contact or group.
export_messages	Export stored messages as JSON or CSV. Supports recipient and since filters.

CLI Usage

# Status & daemon
signal-mcp status                          # account + daemon info
signal-mcp daemon                          # start daemon in foreground
signal-mcp stop                            # stop the daemon

# Send & receive
signal-mcp send [phone] "Hello!"
signal-mcp send-group <group_id> "Hey!"
signal-mcp note "Remember to buy milk"     # save a note to yourself
signal-mcp receive                         # poll once
signal-mcp receive --watch                 # keep watching (saves to store)

# Edit
signal-mcp edit [phone] <timestamp> "corrected text"
signal-mcp edit <group_id> <timestamp> "corrected text"

# Pin / unpin / admin-delete messages
signal-mcp pin [phone] <timestamp> [phone]
signal-mcp unpin [phone] <timestamp> [phone]
signal-mcp admin-delete <group_id> <timestamp> [phone]

# Devices
signal-mcp update-device <device_id> "My Laptop"

# Contacts & groups
signal-mcp contacts
signal-mcp contacts --json
signal-mcp groups
signal-mcp conversations                   # list all chats with unread count + last message

# History & search
signal-mcp history [phone]
signal-mcp history [phone] --limit 20
signal-mcp history [phone] --limit 20 --offset 20   # page 2
signal-mcp history [phone] --since 2024-01-01
signal-mcp search "keyword"
signal-mcp search "keyword" --sender [phone]   # restrict to one contact
signal-mcp search "keyword" --limit 20
signal-mcp store-stats

# Export
signal-mcp export                                          # all messages as JSON to stdout
signal-mcp export messages.json                            # save to file
signal-mcp export messages.csv --format csv                # CSV format
signal-mcp export --recipient [phone] --format csv     # one conversation
signal-mcp export --since 2024-01-01                       # messages from date

# Signal Desktop import (macOS)
signal-mcp import-desktop

# Background service (macOS LaunchAgent or Linux systemd)
signal-mcp install-service    # auto-starts on login, captures all messages
signal-mcp uninstall-service

# MCP server (for Claude Code)
signal-mcp serve

Getting full message history

signal-cli only delivers new messages — it has no history API. Two ways to get history:

Going forward (captures everything from now on):

signal-mcp install-service   # background watcher, auto-starts on login

Retroactively (imports everything from Signal Desktop):

signal-mcp import-desktop    # macOS will prompt for Keychain access — click Allow

Run both for complete coverage.

Architecture

Claude Code
    │  MCP (stdio transport)
    ▼
signal-mcp serve
    ├── SQLite store  (~/.local/share/signal-mcp/messages.db)
    │     FTS5 full-text search, sent + received messages
    │
    └── signal-cli daemon  (JSON-RPC on localhost:7583)
            │  Signal protocol (libsignal)
            ▼
        Signal network

The signal-cli daemon starts automatically on first use and stays alive across tool calls. Received attachments are saved to ~/Downloads/signal-attachments/.

Development

git clone https://github.com/googlarz/signal-mcp
cd signal-mcp
uv sync --dev
uv run pytest
uv run pytest --cov --cov-report=term-missing

All tests are fully mocked — no signal-cli installation or Signal account required to run them.

See CONTRIBUTING.md for how to add new tools.

License

MIT — see LICENSE.