Telegram MCP — AI 에이전트를 위한 로컬 read-only 액세스

로컬 MCP 서버는 Codex, Claude 및 기타 MCP 클라이언트에게 세 가지 도구를 제공합니다:

서버는 읽기 전용으로만 작동합니다. 코드에는 메시지 전송, 편집 또는 삭제 도구가 없습니다. 서버는 STDIO를 통해 로컬에서 실행되며 의도적으로 네트워크 HTTP/SSE 액세스를 제공하지 않습니다.

지원되는 클라이언트

• ChatGPT/Codex Desktop;

• Codex CLI 및 IDE 확장 기능;

• Claude Code;

• Claude Desktop;

• STDIO를 지원하는 모든 로컬 MCP 클라이언트.

로컬 서버는 chatgpt.com, claude.ai, 휴대폰 또는 다른 컴퓨터에서는 직접 작동하지 않습니다. 이러한 환경에서는 사용자 컴퓨터에서 프로세스를 실행할 수 없습니다.

Related MCP server: tdl-mcp

필요한 것

• Windows 10/11, macOS 또는 Linux;

• Git;

• Python 3.10+;

• 지원되는 MCP 클라이언트가 하나 이상 있어야 합니다.

초보자용 설치

1. 터미널 열기

• macOS: Command + Space → Terminal 입력 → Enter.

• Windows: 시작 메뉴 → PowerShell 입력 → PowerShell 열기.

• Linux: Ctrl + Alt + T를 누르거나 Terminal 앱을 엽니다.

2. 프로젝트 다운로드

macOS/Linux:

git clone https://github.com/iamalexzatcepin/telegram-mcp-template.git ~/telegram-mcp
cd ~/telegram-mcp

Windows PowerShell:

git clone https://github.com/iamalexzatcepin/telegram-mcp-template.git "$env:USERPROFILE\telegram-mcp"
cd "$env:USERPROFILE\telegram-mcp"

GitHub에서 저장소를 찾을 수 없다고 표시되면 현재 계정에 비공개 저장소에 대한 액세스 권한이 아직 없는 것입니다.

3. Telegram API ID 및 API Hash 받기

1. my.telegram.org을 엽니다.

2. 전화번호로 로그인합니다.

3. API development tools를 엽니다.

4. 예를 들어 Local Telegram MCP와 같은 앱을 만듭니다.

5. api_id와 api_hash를 저장합니다.

api_hash, 로그인 코드 또는 클라우드 비밀번호를 AI 채팅에 보내지 마세요.

로컬 .env 파일을 만듭니다.

macOS/Linux:

cp .env.example .env
nano .env

Nano에서 저장: Ctrl + O → Enter → Ctrl + X.

Windows PowerShell:

Copy-Item .env.example .env
notepad .env

파일을 로컬에서 작성합니다:

TELEGRAM_API_ID=ваш_api_id
TELEGRAM_API_HASH=ваш_api_hash

4. 종속성 설치 및 Telegram 로그인

macOS/Linux:

bash setup.sh

Windows PowerShell:

powershell -ExecutionPolicy Bypass -File setup.ps1

스크립트가 Python 3.10+를 자동으로 찾아 .venv를 만들고 종속성을 설치한 다음 전화번호, Telegram에서 받은 코드, 그리고 활성화된 경우 클라우드 비밀번호를 요청합니다. 이러한 정보는 자신의 터미널에서만 입력하세요.

에이전트에 연결

모든 예제에서 setup 스크립트가 출력하는 절대 경로를 사용하세요. 명령은 .venv 안의 Python이고, 인자는 telegram_mcp_server.py입니다.

Codex CLI 및 ChatGPT/Codex Desktop

macOS/Linux:

codex mcp add telegram -- "$HOME/telegram-mcp/.venv/bin/python" "$HOME/telegram-mcp/telegram_mcp_server.py"
codex mcp get telegram

Windows PowerShell:

codex mcp add telegram -- "$env:USERPROFILE\telegram-mcp\.venv\Scripts\python.exe" "$env:USERPROFILE\telegram-mcp\telegram_mcp_server.py"
codex mcp get telegram

ChatGPT/Codex Desktop에서도 Settings → MCP servers → Add server를 열고 STDIO를 선택한 다음 동일한 Command와 Arguments를 지정할 수 있습니다. 저장한 후 Restart를 누르세요. 동일한 Codex 호스트의 로컬 클라이언트는 ~/.codex/config.toml 구성을 공유합니다.

Claude Code

macOS/Linux:

claude mcp add --transport stdio --scope user telegram -- "$HOME/telegram-mcp/.venv/bin/python" "$HOME/telegram-mcp/telegram_mcp_server.py"
claude mcp get telegram

Windows PowerShell:

claude mcp add --transport stdio --scope user telegram -- "$env:USERPROFILE\telegram-mcp\.venv\Scripts\python.exe" "$env:USERPROFILE\telegram-mcp\telegram_mcp_server.py"
claude mcp get telegram

새 Claude Code 세션을 시작하고 /mcp를 입력하세요. user 범위는 이 사용자의 여러 로컬 프로젝트에서 서버를 사용할 수 있게 합니다.

Claude Desktop

Developer/MCP 설정을 열고 로컬 STDIO 서버를 추가하세요. 사용 중인 Claude Desktop 버전이 JSON 구성을 사용한다면 나머지 서버를 유지한 채 객체를 추가하세요:

{
  "mcpServers": {
    "telegram": {
      "command": "/absolute/path/to/telegram-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/telegram-mcp/telegram_mcp_server.py"]
    }
  }
}

일반적인 파일 위치:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json;

• Windows: %APPDATA%\Claude\claude_desktop_config.json.

Claude Desktop을 완전히 다시 시작하고 새 채팅을 여세요.

기타 STDIO MCP 클라이언트

동등한 구성을 사용하세요:

{
  "mcpServers": {
    "telegram": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/telegram_mcp_server.py"]
    }
  }
}

최종 확인

에이전트에게 요청하세요:

telegram list_chats를 limit=10으로 사용해 이름, 유형, 읽지 않은 메시지 수를 표시해.

에이전트가 실제로 내 채팅 목록을 반환하기 전까지는 설치가 완료된 것으로 간주하지 마세요.

여러 계정

서버는 default, work, personal 등 별도의 로컬 세션을 지원합니다. 자세한 내용은 docs/MULTI_ACCOUNT.md를 참조하세요.

AI 에이전트용 지침

설치를 Codex, Claude 또는 다른 에이전트가 수행하는 경우, 해당 에이전트에게 docs/AGENT_SETUP.md를 전체적으로 읽고 한 단계씩 따르도록 요청하세요. 이 파일에는 보안 규칙과 다양한 OS에 대한 분기 사항이 기록되어 있습니다.

보안 및 제한 사항

• .env 및 sessions/는 Git에서 제외됩니다;

• .session 파일은 계정에 대한 액세스 권한을 제공합니다 — 복사하거나 게시하지 마세요;

• 미디어 파일은 다운로드되지 않으며 has_media 표시만 반환됩니다;

• Telegram 요청은 사용자 계정을 대신하여 수행되며 Telegram의 제한을 따릅니다;

• 동일한 .session으로 두 작업을 동시에 실행하지 마세요;

• 이 서버를 인터넷에 노출하지 마세요.

자세한 내용: SECURITY.md.

문제가 발생하는 경우

docs/TROUBLESHOOTING.md를 참조하세요.

개발

.venv/bin/python -m unittest discover -s tests -v

프로젝트 구조:

라이선스

MIT — 이 프로젝트는 저작권 고지와 라이선스 전문을 유지하는 조건으로 사용, 수정, 배포할 수 있습니다.