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 전송

설정

필수 조건

• 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

선택적 환경 변수:

셸에 설정된 환경 변수가 .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"]
    }
  }
}

아키텍처

데이터 흐름

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

도구

개인정보 보호 및 보안

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

• 읽기/검색은 로컬 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를 참조하세요.