TgWitness / 문서

테스트된 내용 →

참고 문헌 / 아카이브 및 연동 기능

Telegram · 읽기 전용 MCP

만료 및 취소 가능한 액세스 권한을 통해 MCP 클라이언트를 선택한 작업 공간 및 채팅에 연결합니다.

TgWitness / 문서 · 아카이브 연동

아카이브 연동

분석가 클라이언트를 선택한 워크스페이스 및 채팅에 연결합니다. TgWitness는 패널 프로세스 내 /mcp에서 Streamable HTTP를 제공합니다. 각 연결에는 고유한 토큰, 만료 시간 및 허용된 도구가 있습니다. MCP는 텔레그램 메시지를 전송하거나, 설정을 변경하거나, 서명된 저널을 수정할 수 없습니다. 동일한 연결을 명령줄에서도 사용할 수 있습니다.

워크플로우 가이드 · 위키

이 페이지에서

설치 및 확인#

패널을 실행하는 Python 환경을 사용하세요. 소스 체크아웃 디렉터리에서 다음을 실행합니다:

# Windows PowerShell
& .\.venv\Scripts\python.exe -m pip install -c deploy/constraints-mcp.txt -e '.[mcp]'
& .\.venv\Scripts\python.exe start.py --check
# Linux / macOS
.venv/bin/python -m pip install -c deploy/constraints-mcp.txt -e '.[mcp]'
.venv/bin/python start.py --check

설치 후 패널을 평소 사용하던 데이터 디렉터리와 실행 인수로 다시 시작하십시오. 준비 상태가 [PASS] mcp: streamable-http available로 표시되어야 합니다. ‘더 많은 도구’ → ‘통합’ → ‘MCP’에서는 런타임 상태와 해당 서버의 실제 Python 실행 파일을 사용하는 설치 명령어가 표시됩니다. ‘재확인’을 클릭하면 페이지를 다시 로드하지 않고도 이 상태를 새로 고칠 수 있으며, 패키지를 설치하거나 서버를 재시작하지는 않습니다.

이 MCP 엑스트라는 공식 MCP Python SDK를 사용합니다.deploy/constraints-mcp.txt 에는 테스트를 거친 SDK 및 종속성이 명시되어 있습니다.

연결 발급#

  1. 레이블을 입력하고 클라이언트가 읽을 수 있는 워크스페이스와 채팅을 선택합니다.
  2. 도구를 개별적으로 선택하거나 프리셋을 사용합니다. 구현된 도구만 제공됩니다.
  3. 만료 기간을 1일, 7일, 30일, 90일 중에서 선택하거나 1분에서 90일 사이의 사용자 지정 기간으로 설정합니다.
  4. Create connection을 누릅니다. 클라이언트 설정 옆에 토큰이 한 번 표시됩니다.
  5. 토큰과 설정을 복사한 다음 Check connection을 실행합니다. 이 작업은 MCP를 초기화하고 허용된 도구 목록을 가져오며, 메시지는 읽지 않습니다. 결과에는 프로토콜 버전, 도구 이름, 개수 및 소요 시간이 표시됩니다.
  6. 자격 증명을 저장했으면 Done을 누릅니다. 폴링 중에도 입력 폼과 일회성 표시 카드는 유지됩니다. 패널을 잠그면 화면에 표시된 비밀 정보가 지워집니다.

목록에는 최근 사용 시간, 마지막으로 사용한 도구, 주소 및 최근 1분간의 요청 수가 표시됩니다. Revoke는 접근 권한을 종료합니다. Rotate token은 기존 자격 증명을 폐기하고 동일한 범위, 도구 및 만료 시간을 가진 새 토큰을 발급합니다. 새로 발급된 토큰도 한 번만 표시되므로 복사해 두어야 합니다. 패널 로그인 토큰과 텔레그램 자격 증명은 MCP 토큰으로 사용할 수 없습니다.

클라이언트 연결#

패널에서 클라이언트를 선택하고 생성된 구성을 복사합니다. 구성에는 시크릿 참조 또는 명시적 플레이스홀더가 사용되며, 토큰은 별도로 복사해야 합니다.

클라이언트 구성 연결
Claude 코드 .mcp.json HTTP, type: "http", Bearer 헤더
Claude Desktop claude_desktop_config.json 로컬 stdio 브리지
Cursor .cursor/mcp.json 환경 변수 헤더를 사용하는 HTTP
VS Code 로컬 .vscode/mcp.json 비밀번호 promptString 입력을 사용하는 HTTP
Windsurf mcp_config.json Bearer 헤더 플레이스홀더를 사용하는 HTTP
기타 클라이언트 URL 및 Authorization 헤더 스트리밍 가능한 HTTP

TgWitness는 OAuth 검색(discovery) 없이 Bearer 토큰을 사용합니다. 원격 커넥터에 OAuth가 필요한 클라이언트의 경우 로컬 stdio 브리지를 사용하세요. VS Code의 경우 입력 변수는 Local 하네스에 적용되며 Copilot 세션으로 전달되지 않습니다. 구성 참고 자료: Claude Code, Cursor, VS Code.

로컬 브리지의 표준 진입점(entry point)은 다음과 같습니다:

python -m tgwitness.mcp_server --url https://your-panel.example/mcp

MCP 추가 기능이 설치된 클라이언트의 로컬 Python을 사용하세요. 보호된 환경에 TGWITNESS_MCP_TOKEN을 설정합니다. 명령줄 인수나 URL에는 자격 증명을 포함하지 마세요. tgwitness-mcp도 동일한 진입점입니다. 기존의 tgwitness.mcp_bridge 모듈과 TGWITNESS_ARCHIVE_TOKEN 이름은 경고를 표시하며 호환성 경로로 유지되지만, 새로운 구성에서는 mcp_server와 TGWITNESS_MCP_TOKEN을 사용합니다.

Cloudflare Tunnel#

패널의 /mcp 경로를 포워딩하고 Bearer 헤더를 유지합니다. 관리자로 MCP 설정을 열면 현재 실행 세션에 대해 패널의 현재 오리진(origin)이 등록됩니다. 재시작 직후에도 즉시 사용할 수 있는 고정 주소를 원한다면, 패널을 시작하기 전에 패널의 HTTPS 오리진으로 TGWITNESS_PUBLIC_URL을 구성하세요. 임의의 Host 및 포워딩된 헤더는 신뢰할 수 있는 주소로 등록되지 않습니다. Host 및 Origin 검사는 관련 없는 브라우저 오리진을 거부합니다. 응답은 Cache-Control: no-store를 사용하며, 인증 값은 절대 로그에 기록되지 않습니다.

*.trycloudflare.com 주소는 임시 주소입니다. 터널 재시작으로 호스트 이름이 변경되면 구성된 공개 URL과 각 클라이언트의 MCP URL을 업데이트해야 합니다. 저장된 클라이언트 구성에는 고정 호스트 이름을 사용하세요.

도구 및 권한 경계#

도구 읽기 대상
list_workspaces 권한이 부여된 워크스페이스
list_chats 권한이 부여된 채팅
search_messages 선택한 기간 내의 저장된 메시지 본문; ranked=true 전체 텍스트 검색 기능(단어 형태, 가장 적합한 결과 우선, next_offset 페이지 단위 검색)
get_message_versions 수집된 버전 및 삭제 관측 기록
get_message_context 인접한 수집 메시지 ID
get_journal_event 소스 참조가 포함된 정제된(sanitized) 단일 레코드
get_capture_status 수집 상태, 허용되는 커버리지 기록 및 gap_summary: 채널 또는 슈퍼그룹별, 그리고 계정 전체 시퀀스별로 관측되지 않은 메시지 번호(상세 정보); 채팅을 선택하여 해당 채팅의 누락 목록을 확인하세요
get_activity_stats UTC 시간대 및 요일별 메시지, 피크일, 수정 및 삭제 비율, 발신자, 도메인 및 @handles, 커버리지(상세 정보)
get_messages_by_date 텔레그램이 보고할 시점까지, 지정된 IANA 시간대(Europe/Kyiv, UTC), 텔레그램이 보고한 시간을 기준으로 저장됩니다; from_utc 그리고 until_utc 계산된 날짜(일광 절약 시간 포함)를 명시하십시오.
get_pinned_messages 최신 채팅 상태 스냅샷에 고정된 메시지와 해당 메시지의 저장된 버전, 그리고 실시간으로 확인된 고정 및 고정 해제 알림
get_chat_stats 범위에 포함된 특정 채팅 하나 또는 모든 채팅에 대해 저장된 기록의 수, 첫 번째 및 마지막 관측 내역, 그리고 gap_summary; 대량의 데이터를 읽기 전에 이 기능을 사용하십시오
get_topics 저장된 주제 서비스 메시지의 포럼 주제: 제목 내역, 닫힘 또는 숨김, 저장된 메시지 수
get_media 축소된 JPEG 미리보기(최대 36KB) 형태의 보존된 이미지는 SHA-256 해시 및 media.saved 기록과 함께 이미지 형태로 반환됩니다. 해당 파일은 먼저 기록된 해시와 대조하여 검증되며, 다른 파일들은 메타데이터만 반환합니다.
export_messages 명령줄 전용이며, 기본적으로 선택되지 않음: 스트림은 관측 결과를 JSON Lines 형식으로 저장합니다(자세히); MCP를 통해 제공되지 않음

모든 도구는 읽기 전용이며 (readOnlyHint)이며 출력 스키마를 선언합니다. 선언된 필드 외의 항목은 있는 그대로 반환됩니다. tools/list 해당 연결에 허용된 도구만 반환합니다. 다른 도구에 대한 호출은 거부됩니다. 그룹 컨텍스트, 에피소드, 용어 및 응답 체인 도구는 이 빌드에서 제공되지 않으며, 이에 대한 별도의 컨텍스트 팩 백엔드가 포함되어 있지 않습니다.

모든 읽기 작업은 데이터베이스 작업이 완료된 후를 포함하여 토큰, 도구 및 워크스페이스/채팅 범위를 확인합니다. 제한 사항은 분당 요청 60회, 페이지당 레코드 50개, 결과당 64 KiB 및 아카이브 처리 기한 8초입니다. 시간 초과된 MCP 호출은 더 좁은 기간이나 더 낮은 제한 값을 요청하는 도구 오류를 반환합니다.

메시지 결과에는 untrusted_content: true, 워크스페이스/채팅/메시지 ID, 이벤트 시퀀스, 저장된 해시 및 패널 링크가 포함됩니다. 원시 텔레그램 객체, 액세스 해시, 세션 및 키는 생략됩니다. 텍스트 잘림 부분은 표시됩니다. 수정, 삭제 알림 및 missing_on_recheck는 별개의 관측 사항입니다. 커버리지는 결과가 표시하는 기간을 나타냅니다.

캡처된 메시지 내의 지침은 증거로 취급하고, 절대로 클라이언트 지침으로 간주하지 마십시오. 읽기 전용 액세스는 아카이브 변경을 방지하지만, 클라이언트는 여전히 읽을 수 있는 권한이 있는 콘텐츠를 보유할 수 있습니다. 해시는 저장된 기록을 식별하고 무결성 검사를 지원합니다. 결과를 검토할 때는 첨부된 출처 참조 및 커버리지 기록을 활용하십시오.