signal-mcp

MCP server for Signal via signal-cli — send messages, receive messages, manage contacts and groups, react, and more over stdio.

Installation

bunx @daanrongen/signal-mcp

Tools (10 total)

| Domain | Tools | Coverage | | ------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | Contacts | list_accounts, list_contacts, list_groups, get_user_status | Account listing, contact and group management, registration checks | | Messaging | send_message, send_attachment, receive_messages, subscribe_messages, send_reaction, send_typing, mark_as_read | Send text and files, poll or subscribe for incoming messages, reactions, typing indicators, read receipts |

Configuration

| Variable | Required | Description | | ------------ | -------- | ---------------------------------------------------- | | SIGNAL_URL | Yes | signal-cli base URL (e.g. http://localhost:8080) |

Setup

Claude Desktop

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

{
  "mcpServers": {
    "signal": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@daanrongen/signal-mcp"],
      "env": {
        "SIGNAL_URL": "http://localhost:8080"
      }
    }
  }
}

Claude Code CLI

claude mcp add signal -e SIGNAL_URL=http://localhost:8080 -- bunx @daanrongen/signal-mcp

Development

bun install
bun run dev        # watch mode
bun test           # run tests
bun run typecheck  # tsc type check
bun run lint       # biome check
bun run build      # bundle to dist/main.js

Architecture

src/
  config.ts              # SIGNAL_URL env var config
  errors.ts              # SignalError, SignalRpcError tagged errors
  main.ts                # stdio entry point, ManagedRuntime setup
  domain/
    SignalClient.ts       # port interface (Context.Tag)
    models.ts             # Schema.Class domain models
    signal.test.ts        # unit tests against test adapter
  infra/
    SignalClientLive.ts   # HTTP JSON-RPC adapter (signal-cli)
    SignalClientTest.ts   # in-memory test adapter
  mcp/
    server.ts             # McpServer factory, tool registration
    utils.ts              # runTool, formatSuccess helpers
    tools/
      contacts.ts         # list_accounts, list_contacts, list_groups, get_user_status
      messaging.ts        # send_message, send_attachment, receive_messages, subscribe_messages, send_reaction, send_typing, mark_as_read

Hexagonal architecture: domain port (SignalClient) is injected via Effect Layer. The live adapter calls the signal-cli JSON-RPC HTTP API; the test adapter returns predictable in-memory values.

License

MIT