mcp-signal

A local Model Context Protocol (MCP) server that reads Signal Desktop history from the local encrypted database via signal-export and sends outbound messages via signal-cli.

mcp-signal focuses on the core workflow for personal Signal automation — list chats, read messages, search messages, inspect groups, and send messages to direct or group chats. Everything runs locally; stdio transport by default (no network listener), with an optional HTTP mode available.

Heads up — mixed backend. Read/search comes from the local Signal Desktop database. Sending uses signal-cli, which must be installed and linked to a Signal account separately. If signal-cli is unavailable, read/search still works but send tools do not.

Features

• List direct and group chats from Signal Desktop

• Read recent messages from a chat

• Search messages within one chat or across all chats

• List group chats with signal-cli group IDs for outbound use

• Send a message to:

  • a direct recipient by phone number

  • a group by group ID

  • a chat by exact chat name (with ambiguity checks)

• Runs entirely on your machine; stdio transport by default (no network listener), with an optional HTTP mode

Related MCP server: Signal MCP

Setup

Prerequisites

• Python 3.12+

• uv

• Signal Desktop with an existing local message database

• signal-cli installed and linked if you want outbound sends

Installation

1. Clone this repository

   git clone https://github.com/Sealjay/mcp-signal.git
   cd mcp-signal

2. Install dependencies

   uv sync

3. Install signal-cli (optional — only needed for outbound sends)

   On macOS, the simplest route is Homebrew:

   brew install signal-cli

Configure outbound sends

The server auto-loads a local .env.local file from the repo root if present. This file is gitignored and is the recommended place for machine-local config.

cat > .env.local <<'EOF'
SIGNAL_ACCOUNT="+441234567890"
EOF

Optional environment variables:

Environment variables set in the shell take precedence over .env.local.

MCP_* variables must be set in the shell/environment, not .env.local — the local env loader only picks up SIGNAL_-prefixed keys from that file.

Link signal-cli (first run only)

mcp-signal does not manage linking itself. Link the local signal-cli device first:

signal-cli link -n "signal-mcp"

Scan the QR code in the Signal mobile app (Settings → Linked Devices → Link New Device).

Do not pass -a / --account to link on current signal-cli versions — linking a new secondary device does not take a phone number there.

After the QR is accepted, confirm the linked account is visible:

signal-cli listAccounts

That account should match the SIGNAL_ACCOUNT value in .env.local.

signal-cli stores its linked-account state under its own local data directory (typically ~/.local/share/signal-cli/data on macOS/Linux). That state lives outside this repository and is not committed by mcp-signal.

Verify everything is connected:

uv run signal-mcp smoke

HTTP mode (optional)

By default signal-mcp serve runs over stdio. To serve over streamable HTTP instead, pass --http (optionally with --listen-addr), or set MCP_LISTEN_ADDR in the environment:

uv run signal-mcp serve --http --listen-addr 0.0.0.0:8765

Set MCP_AUTH_TOKEN to require a bearer token on all HTTP routes except /health.

MCP client configuration

All clients launch the server the same way over stdio. On macOS, you may need the absolute path to uv — see macOS: uv PATH below.

Claude Code

The quickest route is the CLI:

claude mcp add --transport stdio signal --scope user -- uv run --directory /absolute/path/to/mcp-signal signal-mcp serve

Alternatively, add to .mcp.json at your project root (or ~/.claude.json for a user-scoped server):

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

If you edit the file directly, restart the Claude Code session to pick it up.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

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

Restart Claude Desktop. You should see signal listed as an available integration.

Cursor

Add to ~/.cursor/mcp.json:

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

Restart Cursor.

macOS: uv PATH

GUI apps (Claude Desktop, Cursor) don't always inherit the PATH from your interactive terminal, so uv may fail with spawn uv ENOENT. Fix by using the absolute path to uv in command:

• Homebrew — /opt/homebrew/bin/uv (Apple Silicon) or /usr/local/bin/uv (Intel)

• Manual install — run which uv in your terminal to find it

Example:

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

Architecture

Data flow

1. The MCP client launches signal-mcp serve over stdio.

2. Read/search tools call signal-export against the local Signal Desktop database.

3. Group listing and outbound sends call signal-cli -a ACCOUNT jsonRpc.

4. Results are returned as structured JSON.

Project structure

mcp-signal/
  src/mcp_signal/
    config.py
    main.py
    reader.py
    server.py
    signal_cli.py
  tests/
  CLAUDE.md
  LICENSE
  README.md
  SECURITY.md

Tools

Privacy and security

• No cloud relay. stdio transport by default (no network listener); optional HTTP mode with bearer auth available. All data stays on your machine.

• Read/search uses your local Signal Desktop data only.

• Send operations require a locally configured signal-cli account.

• .env.local is intended for local secrets such as SIGNAL_ACCOUNT and is not committed.

• signal-cli linked-device state is stored in its own local app data directory, outside this repo, and is not committed.

See SECURITY.md for how to report vulnerabilities.

Limitations

• Prompt-injection risk: as with many MCP servers, this one is subject to the lethal trifecta. Malicious incoming messages could attempt to instruct an agent to exfiltrate other messages. Treat the tool surface accordingly and review outbound actions before approving them.

• Mixed backend: chat history comes from Signal Desktop, while outbound sends come from signal-cli.

• No attachments: text-only send.

• No real-time notifications: polling/read only.

• Single account per MCP instance.

• Group sends need signal-cli: local DB reads alone do not provide enough information to send to groups safely.

Development

uv sync
uv run signal-mcp smoke
uv run pytest
uv run ruff check .

Troubleshooting

• signal-cli not found — confirm signal-cli is on PATH or set SIGNAL_CLI_PATH in .env.local. On macOS, brew install signal-cli is the simplest route.

• Read/search works but sends fail — signal-cli is not linked or SIGNAL_ACCOUNT is not set. Run signal-cli listAccounts to verify, then check .env.local.

• signal-cli link hangs or fails — do not pass -a / --account to link on current versions. Run signal-cli link -n "signal-mcp" and scan the QR from your phone.

• MCP client can't launch the server — args must contain an absolute path to the repo, not relative. If uv itself fails with spawn uv ENOENT, see macOS: uv PATH.

• No messages returned — confirm Signal Desktop is installed and has message history. The read path queries the local Signal Desktop database directly.

Contributing

Contributions welcome via pull request. Please:

• Run uv run ruff check . before pushing.

• Ensure uv run pytest passes.

See CLAUDE.md for the full development workflow.

Licence

MIT Licence — see LICENSE.