mcp-signal
mcp-signal
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+
기존 로컬 메시지 데이터베이스가 있는 Signal Desktop
아웃바운드 전송을 원하는 경우 설치 및 연결된
signal-cli
설치
저장소 복제
git clone https://github.com/Sealjay/mcp-signal.git cd mcp-signal의존성 설치
uv syncsignal-cli설치 (선택 사항 — 아웃바운드 전송에만 필요)macOS의 경우 Homebrew를 사용하는 것이 가장 간단합니다:
brew install signal-cli
아웃바운드 전송 구성
서버는 저장소 루트에 .env.local 파일이 있으면 자동으로 로드합니다. 이 파일은 gitignore 처리되며 기기 로컬 구성을 위한 권장 위치입니다.
cat > .env.local <<'EOF'
SIGNAL_ACCOUNT="+441234567890"
EOF선택적 환경 변수:
변수 | 목적 |
|
|
| Signal Desktop 데이터 디렉토리 재정의 |
| 필요한 경우 암호화된 데스크톱 DB용 비밀번호 |
| 필요한 경우 암호화된 데스크톱 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 smokeMCP 클라이언트 구성
모든 클라이언트는 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 Desktop 데이터에서 직접 읽음 |
데이터 흐름
MCP 클라이언트가 stdio를 통해
signal-mcp serve를 실행합니다.읽기/검색 도구가 로컬 Signal Desktop 데이터베이스에 대해
signal-export를 호출합니다.그룹 목록 조회 및 아웃바운드 전송이
signal-cli -a ACCOUNT jsonRpc를 호출합니다.결과가 구조화된 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도구
도구 | 목적 |
| Signal Desktop의 개인 및 그룹 채팅 목록 조회 |
| 특정 채팅의 메시지 읽기 |
| 특정 채팅 내 또는 전체 채팅에서 메시지 검색 |
| 그룹 ID를 포함한 |
| 개인 수신자 또는 그룹으로 텍스트 메시지 전송 |
| 데스크톱 DB / |
개인정보 보호 및 보안
클라우드 릴레이 없음. 네트워크 리스너 없음. 모든 데이터는 사용자 기기에 유지됩니다.
읽기/검색은 로컬 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:uvPATH를 참조하세요.메시지가 반환되지 않음 — Signal Desktop이 설치되어 있고 메시지 기록이 있는지 확인하세요. 읽기 경로는 로컬 Signal Desktop 데이터베이스를 직접 쿼리합니다.
기여
풀 리퀘스트를 통한 기여를 환영합니다. 다음을 수행하세요:
푸시하기 전에
uv run ruff check .를 실행하세요.uv run pytest가 통과하는지 확인하세요.
전체 개발 워크플로우는 CLAUDE.md를 참조하세요.
라이선스
MIT 라이선스 — LICENSE를 참조하세요.
Available Tools
9 toolschat_activityChat ActivityARead-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 StatusARead-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 ChatsARead-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 GroupsARead-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 MessagesARead-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 MessagesARead-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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
Your own WhatsApp as an MCP server: read, search and send from any MCP client.
Hosted WhatsApp MCP server: send and read messages from your own linked number. OAuth sign-in.
Hosted WhatsApp MCP server: read, search and reply to your own WhatsApp chats from your AI.
MCP connector for iMessage & Contacts via a local Mac agent + Vercel relay
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceMCP Server for retrieving Signal messages using signal-export logic.8-
- AlicenseAqualityAmaintenanceThe most complete Signal MCP server and CLI.8192 PyPI13MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for Signal via signal-cli that enables sending and receiving messages, managing contacts and groups, and reacting over stdio.8 npm-
- AlicenseNot gradedqualityBmaintenanceMCP 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-