signal-mcp

Signal Desktop 메시지용 로컬 읽기 전용 Model Context Protocol 서버입니다.

MCP를 지원하는 에이전트에 범위가 좁게 한정된 네 가지 도구를 제공합니다:

• signal_list_conversations — 메시지 본문을 반환하지 않고 최근 개인 및 그룹 대화를 찾습니다.

• signal_get_messages — 정확히 하나의 대화에서 시간순으로 범위가 제한된 구간을 검색합니다.

• signal_search_messages — 리터럴 부분 문자열 검색이며, 선택적으로 대화와 시간 범위로 한정할 수 있습니다.

• signal_get_message — 인용 및 첨부 파일 메타데이터와 함께 정확히 하나의 메시지를 검색합니다.

이 서버는 메시지를 전송하지 않으며 Signal 데이터베이스에 기록하지 않습니다. stdio를 통해 로컬에서 실행되며 HTTP 리스너가 없습니다.

중요한 개인정보 보호 경고

이 서버는 연결하는 MCP 호스트와 모델에 사용자의 비공개 Signal 기록을 노출할 수 있습니다. 해당 호스트의 데이터 처리 정책을 검토하고 요청 범위를 좁게 유지하며, 신뢰하지 않는 에이전트에는 이 서버를 구성하지 마십시오.

Signal Desktop의 로컬 데이터베이스는 공개 API가 아닌 구현 세부 사항입니다. Signal 스키마 업데이트로 이 프로젝트가 일시적으로 중단될 수 있습니다. 이 프로젝트는 비공식 프로젝트이며 Signal Messenger LLC와 제휴하거나 보증하지 않습니다.

Related MCP server: msteams-local-mcp

현재 지원 범위

• Windows

• 동일한 Windows 사용자로 설치된 Signal Desktop

• Node.js 20 이상

• 로컬 stdio MCP 호스트

현재 자동 키 복구에는 Windows가 필요합니다. Signal이 Chromium OSCrypt 마스터 키를 현재 사용자의 DPAPI 자격 증명으로 보호하기 때문입니다.

설치

git clone https://github.com/NathanDai5287/signal-mcp.git
cd signal-mcp
npm install
npm run build

기본적으로 서버는 %APPDATA%\Signal에서 Signal을 찾습니다. 일반적으로 구성이 필요 없습니다.

MCP 호스트를 구성하지 않고 연결을 테스트하려면:

npx @modelcontextprotocol/inspector node dist/src/index.js

Inspector는 실제 비공개 메시지를 반환하는 도구를 호출할 수 있습니다. 그에 따라 브라우저 세션을 취급하십시오.

MCP 호스트 구성

프로젝트를 빌드한 다음 호스트가 절대 경로로 컴파일된 진입점을 실행하도록 구성하십시오:

{
  "mcpServers": {
    "signal": {
      "command": "node",
      "args": ["C:\\path\\to\\signal-mcp\\dist\\src\\index.js"]
    }
  }
}

MCP 구성을 변경한 후 호스트를 다시 시작하십시오. 정확한 구성 파일 위치는 호스트에 따라 다릅니다.

선택적 구성

환경 변수는 MCP 호스트의 서버 구성을 통해 전달됩니다:

SIGNAL_MCP_KEY를 커밋된 파일에 넣지 마십시오. Windows에서는 자동 복구가 더 바람직합니다.

데이터베이스 접근 방식

Signal Desktop은 AES-256-GCM으로 암호화된 SQLCipher 키를 config.json에 저장합니다. 이 키를 감싸는 키는 Windows DPAPI로 보호되는 Chromium의 Local State에 있습니다. 이 서버는 시작할 때 다음을 수행합니다:

1. 현재 Windows 사용자의 OSCrypt 마스터 키에 대한 DPAPI 보호를 해제합니다.

2. Signal의 SQLCipher 키를 메모리에서 복호화합니다.

3. SQLCipher 호환성 수준 4로 데이터베이스를 엽니다.

4. 도구 호출을 처리하기 전에 SQLite query_only 모드를 활성화합니다.

키는 이 프로젝트에 의해 출력되거나, MCP를 통해 반환되거나, 영구 저장되지 않습니다.

모든 검색 입력은 바인딩된 SQL 매개변수입니다. %, _, \는 이스케이프되어 검색어가 호출자가 제어하는 SQL 패턴이 아닌 리터럴 부분 문자열이 됩니다. 모든 결과 집합에는 상한이 적용됩니다.

반환되는 데이터

메시지 결과에는 다음이 포함될 수 있습니다:

• Signal 메시지 및 대화 식별자

• 밀리초 타임스탬프

• 수신/발신 방향

• 발신자 서비스 ID 및 표시 이름

• 메시지 본문

• 비정규화된 인용 답글 텍스트

• 첨부 파일 메타데이터 및 로컬 다운로드 가능 여부

이 마일스톤은 첨부 파일 바이트를 복호화하거나 반환하지 않으며, 영구 아카이브를 만들지 않고, 의미론적 검색을 수행하지 않으며, 메시지를 전송하지 않습니다. Signal이 이미 삭제한 사라지는 메시지는 복구할 수 없습니다.

개발

npm test
npm run check
npm run build

테스트 스위트는 인메모리 가짜 리더를 사용하며 사용자의 Signal 데이터에 접근하지 않습니다. Signal의 비공개 데이터베이스 스키마 변경을 감지하려면 여전히 수동 로컬 스모크 테스트가 필요합니다.

운영 로깅은 stderr로 출력됩니다. stdout은 MCP JSON-RPC 트래픽용으로 예약되어 있기 때문입니다.

보안

메시지 텍스트, 데이터베이스 파일, 키, 서비스 ID, 전화번호 또는 로컬 경로가 포함된 공개 이슈를 열지 마십시오. 비공개 취약점 신고 지침은 SECURITY.md를 참조하십시오.

라이선스

프로젝트 소스는 MIT 라이선스입니다. 종속성은 각자의 라이선스를 유지합니다. 특히 @signalapp/sqlcipher는 AGPL-3.0-only로 배포됩니다.