# Telegram · 읽기 전용 MCP

Canonical page: https://phishdestroy.io/tgwitness/ko/docs/reference/mcp/

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

[Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/)

[Documentation index](https://phishdestroy.io/tgwitness/ko/llms.txt)

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

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [문서](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [아카이브 연동](https://phishdestroy.io/tgwitness/ko/docs/reference/cli/)

![아카이브 연동](https://phishdestroy.io/tgwitness/assets/chapter-integrations.svg?v=367d9d210074)

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

[워크플로우 가이드](https://phishdestroy.io/tgwitness/docs/archive/) · [위키](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md)

**이 페이지에서**

- [설치 및 확인](https://phishdestroy.io/tgwitness/ko/docs/reference/mcp/#install-and-check)
- [연결 요청](https://phishdestroy.io/tgwitness/ko/docs/reference/mcp/#issue-a-connection)
- [클라이언트 연결](https://phishdestroy.io/tgwitness/ko/docs/reference/mcp/#connect-your-client)
- [Cloudflare Tunnel](https://phishdestroy.io/tgwitness/ko/docs/reference/mcp/#cloudflare-tunnel)
- [도구 및 한계](https://phishdestroy.io/tgwitness/ko/docs/reference/mcp/#tools-and-boundaries)

## 설치 및 확인

패널을 실행하는 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를](https://github.com/modelcontextprotocol/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](https://code.claude.com/docs/en/mcp), [Cursor](https://prod.cursor.com/docs/mcp), [VS Code](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).

로컬 브리지의 표준 진입점(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` [전체 텍스트 검색](https://phishdestroy.io/tgwitness/ko/docs/reference/search/) 기능(단어 형태, 가장 적합한 결과 우선, `next_offset` 페이지 단위 검색) |
| `get_message_versions` | 수집된 버전 및 삭제 관측 기록 |
| `get_message_context` | 인접한 수집 메시지 ID |
| `get_journal_event` | 소스 참조가 포함된 정제된(sanitized) 단일 레코드 |
| `get_capture_status` | 수집 상태, 허용되는 커버리지 기록 및 `gap_summary`: 채널 또는 슈퍼그룹별, 그리고 계정 전체 시퀀스별로 관측되지 않은 메시지 번호([상세 정보](https://phishdestroy.io/tgwitness/ko/docs/reference/evidence/#missing-message-numbers-gap_summary)); 채팅을 선택하여 해당 채팅의 누락 목록을 확인하세요 |
| `get_activity_stats` | UTC 시간대 및 요일별 메시지, 피크일, 수정 및 삭제 비율, 발신자, 도메인 및 `@handles`, 커버리지([상세 정보](https://phishdestroy.io/tgwitness/ko/docs/reference/cli/#activity-statistics)) |
| `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 형식으로 저장합니다([자세히](https://phishdestroy.io/tgwitness/ko/docs/reference/cli/#export)); MCP를 통해 제공되지 않음 |

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

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

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

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