Skip to main content
Glama
mcp-signal

mcp-signal

mcp-signal

Python uv MCP License: MIT GitHub issues GitHub stars Sealjay/mcp-signal MCP server

signal-export를 통해 로컬 암호화 데이터베이스에서 Signal Desktop 기록을 읽고, signal-cli를 통해 메시지를 발송하는 로컬 MCP(Model Context Protocol) 서버입니다.

mcp-signal은 개인 Signal 자동화를 위한 핵심 워크플로우(채팅 목록 조회, 메시지 읽기, 메시지 검색, 그룹 검사, 개인 또는 그룹 채팅으로 메시지 전송)에 중점을 둡니다. 모든 작업은 로컬에서 실행되며, 네트워크 리스너 없이 stdio 전송을 사용합니다.

참고 — 혼합 백엔드. 읽기/검색은 로컬 Signal Desktop 데이터베이스에서 수행됩니다. 전송은 별도로 설치 및 Signal 계정에 연결되어야 하는 signal-cli를 사용합니다. signal-cli를 사용할 수 없는 경우에도 읽기/검색 기능은 작동하지만 전송 도구는 작동하지 않습니다.

기능

  • Signal Desktop의 개인 및 그룹 채팅 목록 조회

  • 채팅의 최근 메시지 읽기

  • 특정 채팅 내 또는 전체 채팅에서 메시지 검색

  • 아웃바운드용 signal-cli 그룹 ID와 함께 그룹 채팅 목록 조회

  • 메시지 전송 대상:

    • 전화번호를 통한 개인 수신자

    • 그룹 ID를 통한 그룹

    • 정확한 채팅 이름을 통한 채팅 (중복 확인 포함)

  • 전적으로 사용자 기기에서 실행; 네트워크 리스너 없는 stdio 전송

Related MCP server: Signal MCP

설정

필수 조건

  • Python 3.13+

  • uv

  • 기존 로컬 메시지 데이터베이스가 있는 Signal Desktop

  • 아웃바운드 전송을 원하는 경우 설치 및 연결된 signal-cli

설치

  1. 저장소 복제

    git clone https://github.com/Sealjay/mcp-signal.git
    cd mcp-signal
  2. 의존성 설치

    uv sync
  3. signal-cli 설치 (선택 사항 — 아웃바운드 전송에만 필요)

    macOS의 경우 Homebrew를 사용하는 것이 가장 간단합니다:

    brew install signal-cli

아웃바운드 전송 구성

서버는 저장소 루트에 .env.local 파일이 있으면 자동으로 로드합니다. 이 파일은 gitignore 처리되며 기기 로컬 구성을 위한 권장 위치입니다.

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

선택적 환경 변수:

변수

목적

SIGNAL_CLI_PATH

signal-cli 바이너리 경로 재정의

SIGNAL_DATA_DIR

Signal Desktop 데이터 디렉토리 재정의

SIGNAL_DB_PASSWORD

필요한 경우 암호화된 데스크톱 DB용 비밀번호

SIGNAL_DB_KEY

필요한 경우 암호화된 데스크톱 DB용 원시 키

셸에 설정된 환경 변수가 .env.local보다 우선합니다.

signal-cli 연결 (최초 실행 시에만)

mcp-signal은 연결 자체를 관리하지 않습니다. 먼저 로컬 signal-cli 장치를 연결하세요:

signal-cli link -n "signal-mcp"

Signal 모바일 앱에서 QR 코드를 스캔하세요 (설정 → 연결된 기기 → 새 기기 연결).

현재 signal-cli 버전에서는 link에 -a / --account를 전달하지 마세요. 새 보조 기기를 연결할 때는 전화번호가 필요하지 않습니다.

QR 코드가 승인된 후, 연결된 계정이 보이는지 확인하세요:

signal-cli listAccounts

해당 계정은 .env.local의 SIGNAL_ACCOUNT 값과 일치해야 합니다.

signal-cli는 연결된 계정 상태를 자체 로컬 데이터 디렉토리(macOS/Linux에서는 일반적으로 ~/.local/share/signal-cli/data)에 저장합니다. 이 상태는 이 저장소 외부에 존재하며 mcp-signal에 의해 커밋되지 않습니다.

모든 것이 연결되었는지 확인하세요:

uv run signal-mcp smoke

MCP 클라이언트 구성

모든 클라이언트는 stdio를 통해 동일한 방식으로 서버를 실행합니다. macOS에서는 uv의 절대 경로가 필요할 수 있습니다. 아래 macOS: uv PATH를 참조하세요.

Claude Code

가장 빠른 방법은 CLI를 사용하는 것입니다:

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

또는 프로젝트 루트의 .mcp.json(또는 사용자 범위 서버의 경우 ~/.claude.json)에 추가하세요:

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

파일을 직접 수정하는 경우, Claude Code 세션을 다시 시작하여 변경 사항을 적용하세요.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json(macOS)에 추가하세요:

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

Claude Desktop을 다시 시작하세요. signal이 사용 가능한 통합 항목으로 나열되어야 합니다.

Cursor

~/.cursor/mcp.json에 추가하세요:

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

Cursor를 다시 시작하세요.

macOS: uv PATH

GUI 앱(Claude Desktop, Cursor)은 대화형 터미널의 PATH를 항상 상속받지 않으므로 uv가 spawn uv ENOENT 오류와 함께 실패할 수 있습니다. command에 uv의 절대 경로를 사용하여 해결하세요:

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

  • 수동 설치 — 터미널에서 which uv를 실행하여 경로를 찾으세요

예시:

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

아키텍처

구성 요소

설명

MCP 서버

Python/FastMCP, stdio 전송

읽기 경로

로컬 Signal Desktop 데이터베이스를 읽는 signal-export

전송 경로

요청 시 실행되는 signal-cli JSON-RPC

상태

별도의 캐시 없음; Signal Desktop 데이터에서 직접 읽음

데이터 흐름

  1. MCP 클라이언트가 stdio를 통해 signal-mcp serve를 실행합니다.

  2. 읽기/검색 도구가 로컬 Signal Desktop 데이터베이스에 대해 signal-export를 호출합니다.

  3. 그룹 목록 조회 및 아웃바운드 전송이 signal-cli -a ACCOUNT jsonRpc를 호출합니다.

  4. 결과가 구조화된 JSON으로 반환됩니다.

프로젝트 구조

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

도구

도구

목적

list_chats

Signal Desktop의 개인 및 그룹 채팅 목록 조회

read_messages

특정 채팅의 메시지 읽기

search_messages

특정 채팅 내 또는 전체 채팅에서 메시지 검색

list_groups

그룹 ID를 포함한 signal-cli의 그룹 목록 조회

send_message

개인 수신자 또는 그룹으로 텍스트 메시지 전송

get_status

데스크톱 DB / signal-cli / 계정 준비 상태 표시

개인정보 보호 및 보안

  • 클라우드 릴레이 없음. 네트워크 리스너 없음. 모든 데이터는 사용자 기기에 유지됩니다.

  • 읽기/검색은 로컬 Signal Desktop 데이터만 사용합니다.

  • 전송 작업에는 로컬로 구성된 signal-cli 계정이 필요합니다.

  • .env.local은 SIGNAL_ACCOUNT와 같은 로컬 비밀 정보를 위한 것이며 커밋되지 않습니다.

  • signal-cli 연결된 기기 상태는 이 저장소 외부의 자체 로컬 앱 데이터 디렉토리에 저장되며 커밋되지 않습니다.

취약점 보고 방법은 SECURITY.md를 참조하세요.

제한 사항

  • 프롬프트 주입 위험: 많은 MCP 서버와 마찬가지로 이 서버도 the lethal trifecta의 대상이 될 수 있습니다. 악의적인 수신 메시지가 에이전트에게 다른 메시지를 유출하도록 지시할 수 있습니다. 도구 표면을 적절히 다루고 아웃바운드 작업을 승인하기 전에 검토하세요.

  • 혼합 백엔드: 채팅 기록은 Signal Desktop에서 가져오고, 아웃바운드 전송은 signal-cli에서 수행됩니다.

  • 첨부 파일 없음: 텍스트 전송만 가능합니다.

  • 실시간 알림 없음: 폴링/읽기 전용입니다.

  • MCP 인스턴스당 단일 계정.

  • 그룹 전송 시 signal-cli 필요: 로컬 DB 읽기만으로는 그룹으로 안전하게 전송할 수 있는 충분한 정보가 제공되지 않습니다.

개발

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

문제 해결

  • signal-cli를 찾을 수 없음 — signal-cli가 PATH에 있는지 확인하거나 .env.local에서 SIGNAL_CLI_PATH를 설정하세요. macOS에서는 brew install signal-cli가 가장 간단합니다.

  • 읽기/검색은 되지만 전송이 실패함 — signal-cli가 연결되지 않았거나 SIGNAL_ACCOUNT가 설정되지 않았습니다. signal-cli listAccounts를 실행하여 확인한 후 .env.local을 확인하세요.

  • signal-cli link가 멈추거나 실패함 — 현재 버전에서는 link에 -a / --account를 전달하지 마세요. signal-cli link -n "signal-mcp"를 실행하고 휴대폰으로 QR을 스캔하세요.

  • MCP 클라이언트가 서버를 실행할 수 없음 — args에는 상대 경로가 아닌 저장소의 절대 경로가 포함되어야 합니다. uv 자체가 spawn uv ENOENT 오류로 실패하면 macOS: uv PATH를 참조하세요.

  • 메시지가 반환되지 않음 — Signal Desktop이 설치되어 있고 메시지 기록이 있는지 확인하세요. 읽기 경로는 로컬 Signal Desktop 데이터베이스를 직접 쿼리합니다.

기여

풀 리퀘스트를 통한 기여를 환영합니다. 다음을 수행하세요:

  • 푸시하기 전에 uv run ruff check .를 실행하세요.

  • uv run pytest가 통과하는지 확인하세요.

전체 개발 워크플로우는 CLAUDE.md를 참조하세요.

라이선스

MIT 라이선스 — LICENSE를 참조하세요.

Available Tools

9 tools
chat_activityChat ActivityA
Read-onlyIdempotent

List Signal chats ranked by recent activity, showing last message date, last reply date, and count of unanswered inbound messages.

Read-only with no side effects. Use this to identify chats that need a response. Use list_chats instead for a general chat directory with message previews.

Inputs: limit. Returns: result

decrypt_attachmentDecrypt AttachmentA

Decrypt a locally stored Signal attachment and return the path to the decrypted file.

The encrypted_path and local_key values come from attachment metadata in read_messages or search_messages results. Read-only on Signal data; writes a decrypted copy to a temporary directory (the temp file is not auto-cleaned). Returns the absolute path to the decrypted file as a string on success, or a string starting with 'Error:' on failure (missing file, wrong key length, or HMAC mismatch). Use this after reading messages that contain attachments.

Inputs: local_key (required), encrypted_path (required). Returns: result

get_statusGet StatusA
Read-onlyIdempotent

Check whether the Signal MCP server can read local messages and send outbound messages.

Returns boolean fields: source_dir_exists, signal_cli_available, signal_account_configured, read_available, send_available. Read-only with no side effects. Call this before read or send operations to verify configuration; call pairing_status instead to check first-run device-linking state.

Inputs: no named parameters. Returns: object

list_chatsList ChatsA
Read-onlyIdempotent

List direct and group Signal chats from the local desktop database, sorted by most recent message.

Each result includes name, phone number, message count, and a preview of the last message. Read-only with no side effects. Use this to discover exact chat names before calling read_messages or search_messages. Use list_groups instead when you need group_id values for send_message.

Inputs: limit, query. Returns: result

list_groupsList GroupsA
Read-onlyIdempotent

List Signal groups with group_id, name, description, members, and admin lists, sorted alphabetically.

Read-only with no side effects. Queries signal-cli when available; falls back to the local desktop database (without group_id). Use this to obtain group_id values needed by send_message. Use list_chats instead for a combined view of both direct and group chats.

Inputs: limit, query. Returns: result

pairing_statusPairing StatusA

Report the Signal device-linking setup state for first-run pairing, so a client can surface the live link QR.

Returns a setup_state envelope: state 'ready' with the linked account once signal-cli is linked; 'awaiting_qr' with a 'qr_payload' sgnl://linkdevice URI to scan in Signal (Settings → Linked devices → Link new device) while a link is in progress (no payload yet on the first call, until the URI is captured); or 'error' when signal-cli is unavailable. Read-only from the caller's view, but the first call on an unlinked device starts a background signal-cli link process as a side effect. Poll this to drive a pairing UI; call get_status instead to check read/send availability once linked.

Inputs: no named parameters. Returns: object

read_messagesRead MessagesA
Read-onlyIdempotent

Read messages from a single Signal chat, returned newest-first.

Each message includes sender, date, body text, reactions, and attachment metadata. Read-only with no side effects. Requires an exact chat name from list_chats. Use search_messages instead to find messages by keyword across chats.

Inputs: chat_name (required), after, limit, before, +1 more. Returns: result

search_messagesSearch MessagesA
Read-onlyIdempotent

Search Signal message bodies for a keyword, within one chat or across all chats, returned newest-first.

Each result includes sender, date, chat name, body text, reactions, and attachment metadata. Read-only with no side effects. Use this to find messages by content. Use read_messages instead to browse a specific chat chronologically.

Inputs: query (required), limit, chat_name. Returns: result

send_messageSend MessageA

Send a text message via Signal to a direct recipient or group.

This is a write operation that delivers a real message through signal-cli. Sends are not reversible from this server — Signal supports user-initiated message deletion only via the official clients. Exactly one of phone_number, group_id, or chat_name must be supplied; providing zero or more than one raises an error. Rate-limited to 1 message per recipient per second and 10 messages per 60-second window globally. Requires signal-cli and SIGNAL_ACCOUNT to be configured — call get_status first to verify send_available is true. Returns target_type, target identifier, and timestamp on success.

Inputs: message (required), group_id, chat_name, phone_number. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool has a narrow, distinct purpose, and descriptions explicitly route the agent elsewhere when overlap exists (e.g. chat_activity vs list_chats, read_messages vs search_messages, get_status vs pairing_status). The only natural overlap is list_chats also covering groups, but list_groups is clearly framed as the source of group_id values. An agent should never misselect here.

    Naming Consistency4/5

    Most tools follow a clean verb_noun pattern (list_chats, read_messages, search_messages, send_message, decrypt_attachment). Two names deviate by dropping the verb (chat_activity, pairing_status), where get_ is implied by analogy with get_status. Minor and still readable.

    Tool Count5/5

    Nine tools is well-scoped for a Signal read/send bridge: discovery, reading, search, activity triage, attachment decryption, diagnostic/pairing state, and one write path. No obviously redundant or filler tools.

    Completeness4/5

    Core lifecycle is covered: discover chats/groups, read and search messages, decrypt attachments, check configuration/pairing, and send text messages. Gaps remain on the write side — no sending attachments, no group creation/management, no message deletion — though these are reasonable scope limits rather than dead ends for the stated read-focused purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Signal via signal-cli that enables sending and receiving messages, managing contacts and groups, and reacting over stdio.
      8 npm
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for a local-first messaging workspace that integrates Google Messages, WhatsApp, and Signal. It enables reading, sending, searching messages, and managing conversations through MCP tools.
      73
      -