signal-mcp

Signal Desktop의 암호화된 SQLite 데이터베이스를 직접 읽고, 기존 Python signal-mcp-server보다 더 풍부한 쿼리 도구를 제공하는 Node/TypeScript MCP 서버입니다.

읽기 전용. 데이터베이스는 readonly: true 및 query_only=ON으로 열립니다. 서버는 Signal의 데이터를 수정할 수 없습니다.

요구 사항

• macOS, Signal Desktop이 설치되어 있고 최소 한 번 이상 로그인된 상태여야 합니다.

• Node.js 20+.

• 처음 실행 시 macOS 키체인 프롬프트가 표시됩니다. 승인하십시오(다시 묻지 않게 하려면 항상 허용을 체크하세요). 서버는 SQLCipher 키를 복호화하기 위해 로그인 키체인에서 Signal safeStorage 비밀번호를 읽습니다.

Related MCP server: Cursor DB MCP Server

설치

옵션 A — GitHub에서 설치 (권장)

npm을 통해 전역으로 설치합니다. 저장소의 prepare 스크립트가 자동으로 tsc를 실행하므로 미리 빌드된 dist/가 필요하지 않습니다.

npm install -g git+https://github.com/jagypus/signal-mcp.git

그런 다음 Claude Code에 등록합니다:

claude mcp add signal --scope user -- signal-mcp

끝입니다. Claude Code를 열고 다음을 시도해 보세요: "내 Signal 채팅 목록을 보여줘."

나중에 업데이트하려면:

npm install -g git+https://github.com/jagypus/signal-mcp.git

삭제하려면:

claude mcp remove signal
npm uninstall -g signal-mcp

옵션 B — 복제 및 빌드 (개발용)

git clone https://github.com/jagypus/signal-mcp.git
cd signal-mcp
npm install
npm run build
claude mcp add signal --scope user -- node "$(pwd)/dist/index.js"

옵션 C — 수동 설정

MCP 설정을 직접 편집하려면 Claude Code MCP 서버 설정(예: ~/.claude.json의 mcpServers 블록 또는 프로젝트 .mcp.json)에 다음을 추가하세요:

{
  "mcpServers": {
    "signal": {
      "command": "signal-mcp"
    }
  }
}

…또는 복제된 저장소 경로의 경우:

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

확인

claude mcp list

목록에 signal이 표시되어야 합니다. 이미 실행 중이었다면 Claude Code를 다시 시작한 후 채팅 목록을 요청하세요.

도구

모든 입력은 Zod로 검증됩니다. 타임스탬프는 ISO 8601 형식으로 입출력됩니다.

필터링 규칙

• exclude_system (기본값 true)은 type IN ('incoming','outgoing')인 메시지만 유지하며, keychange, profile-change, group-v2-change, timer-notification 등을 필터링합니다.

• only_with_body (기본값 true)는 body IS NULL인 첨부 파일 전용/반응/스티커 행을 제외합니다.

• sender: me (발신), them (수신), any (둘 다).

개발

git clone https://github.com/jagypus/signal-mcp.git
cd signal-mcp
npm install
npm run build               # compile to dist/
npm run dev                 # tsx, stdio (no build step)
npm run probe               # dump schema/FTS/types against the live DB
npx tsx scripts/smoke.ts    # exercise every tool against the live DB

데이터베이스를 여는 방법

macOS의 Signal Desktop은 SQLCipher v4 데이터베이스를 ~/Library/Application Support/Signal/sql/db.sqlite에 저장합니다. 최신 Signal 버전은 Electron의 safeStorage를 사용하여 config.json의 encryptedKey에 SQLCipher 키를 암호화하여 저장합니다:

• v10/v11 접두사 제거 → AES-128-CBC 암호문.

• 암호화 키 = PBKDF2-HMAC-SHA1(비밀번호, "saltysalt", 1003 반복, 16바이트).

• macOS의 경우, password는 security find-generic-password -s "Signal Safe Storage" -a "Signal" -w를 통해 가져옵니다(처음 실행 시 키체인 프롬프트 발생).

• IV는 16바이트의 0x20입니다.

평문은 64자 16진수 SQLCipher 키입니다. config.json에 평문 key가 있는 구형 Signal 빌드도 지원됩니다.

데이터베이스는 better-sqlite3-multiple-ciphers를 사용하여 readonly: true 모드로 열리며, 안전을 위해 query_only=ON이 설정됩니다. SQLCipher는 WAL을 사용하므로 Signal Desktop이 실행 중일 때도 문제없이 열립니다.

검색 주의 사항

messages_fts가 존재하지만 Signal Desktop의 네이티브 코드에서만 등록되는 Signal의 사용자 지정 signal_tokenizer를 사용합니다. 타사 리더는 이에 대해 MATCH 쿼리를 실행할 수 없으므로, search_messages는 한 번 시도한 후 자동으로 body LIKE '%query%'로 대체합니다.

환경 변수

플랫폼별 참고 사항

• macOS: 지원됨.

• Linux: safeStorage v10은 리터럴 비밀번호 peanuts를 사용합니다. v11(libsecret/KWallet)은 구현되지 않았으므로 SIGNAL_KEY를 명시적으로 설정하세요.

• Windows: 구현되지 않았으므로 SIGNAL_KEY를 명시적으로 설정하세요.

프로젝트 레이아웃

src/
  index.ts             # MCP server bootstrap
  db.ts                # connection + safeStorage key decryption
  schema.ts            # zod input shapes
  util/
    time.ts            # iso <-> ms
    messages.ts        # row shaping, display name resolution
    sql.ts             # shared filter SQL
  tools/
    listChats.ts
    getRecentMessages.ts
    getChatMessages.ts
    searchMessages.ts
    querySql.ts
scripts/
  probe.ts             # live-DB schema dump
  smoke.ts             # live-DB end-to-end check

라이선스

MIT — LICENSE를 참조하세요.

이 프로젝트는 Signal Messenger LLC와 제휴하거나 보증하지 않습니다. Signal Desktop 자체는 AGPL-3.0 라이선스를 따릅니다. 이 프로젝트는 Signal 코드를 재배포하거나 수정하지 않으며, 사용자의 컴퓨터에 Signal Desktop이 생성한 로컬 SQLite 데이터베이스를 읽기만 합니다.