telegram-ask-mcp

Claude(Claude Code 등)가 선택지를 물어야 할 때 터미널 팝업 대신 텔레그램으로 질문을 보내고, 사용자가 폰에서 누른 버튼·번호·자유 텍스트를 답으로 받아오는 MCP 서버.

자리에 없어도 폰으로 Claude의 질문에 답하고 작업을 계속 진행시킬 수 있다.

• 📄 소개 페이지: https://naryeo628.github.io/telegram-ask-mcp/

• 🧩 MCP 서버(stdio) · Python FastMCP · 외부 의존성 없음(표준 라이브러리 + mcp)

┌────────────────────────────────────────┐
│ ❓ 어느 방식으로 배포할까요?            │
│                                        │
│   1. 블루-그린                          │
│   2. 카나리                             │
│   3. 롤링                               │
│                                        │
│ 👉 버튼을 누르거나 번호를 보내세요.     │
│  [ 1. 블루-그린 ]                       │
│  [ 2. 카나리   ]                        │
│  [ 3. 롤링     ]                        │
└────────────────────────────────────────┘
                              나: 2  ↩

목차

1. 동작 방식

2. 사전 준비

3. 1단계 · 텔레그램 봇 만들기

4. 2단계 · 내 chat_id 알아내기

5. 3단계 · 비밀 파일 만들기

6. 4단계 · 설치

7. 5단계 · MCP 클라이언트에 등록

8. 6단계 · 연결 확인

9. "항상 텔레그램으로 묻기" 규칙

10. 도구 레퍼런스

11. 환경변수

12. 문제 해결

13. 보안

14. 개발 · 재배포

Related MCP server: tsgram-mcp

동작 방식

1. Claude가 ask_via_telegram(question, options) 도구를 호출

2. 서버가 텔레그램으로 질문 + 번호 인라인 버튼을 전송

3. 사용자가 버튼 탭 / 번호 입력 / 자유 텍스트 중 하나로 응답

4. 서버가 getUpdates long-poll로 응답을 받아 Claude에 반환

5. 약 10분(TELEGRAM_ASK_WAIT_SEC) 안에 답이 없으면 timeout을 반환 → Claude는 평소처럼 터미널에서 다시 질문

⚠️ 왜 기존 팝업을 자동으로 못 가로채나: MCP 서버는 다른 도구(Claude 내장 AskUserQuestion)를 후킹할 수 없다. 그래서 "묻기"를 담당하는 전용 도구를 만들고, Claude가 질문 상황에서 이 도구를 쓰도록 메모리/규칙으로 유도한다. (아래 참고)

사전 준비

• Python 3.10 이상

• uv (권장 설치 도구) — curl -LsSf https://astral.sh/uv/install.sh | sh

• 텔레그램 계정 (앱 설치된 폰 또는 데스크톱)

• MCP를 지원하는 클라이언트 — Claude Code, Claude Desktop, Cursor 등

1단계 · 텔레그램 봇 만들기 (BotFather)

봇은 텔레그램의 BotFather가 발급한다.

1. 텔레그램에서 @BotFather 검색 → 대화 열기 → Start

2. /newbot 입력

3. 봇 이름(name) 입력 — 표시용. 아무거나 (예: My Claude Asker)

4. 봇 username 입력 — 반드시 bot으로 끝나야 함, 전역에서 유일해야 함 (예: my_claude_asker_bot)

5. 성공하면 BotFather가 토큰을 준다. 이렇게 생긴 문자열:

   8383648698:AAH...(생략)...xyz

   🔐 이 토큰은 비밀번호와 동급. 노출되면 누구나 이 봇을 조종할 수 있다. 채팅·코드·캡처에 남기지 말 것. 잃어버리거나 노출되면 BotFather에서 /token(재확인) 또는 /revoke(재발급).

6. 방금 만든 봇과의 대화를 열고 아무 메시지나 한 번 보낸다 (예: /start 또는 hi).

   ❗ 텔레그램 봇은 사용자가 먼저 말을 걸기 전에는 사용자에게 메시지를 보낼 수 없다. 이 단계를 빼먹으면 나중에 질문이 안 날아온다. (그룹/채널이 아니라 봇과의 1:1 대화여야 함)

2단계 · 내 chat_id 알아내기

봇이 메시지를 보낼 대상(=나)의 숫자 ID. 두 방법 중 편한 것:

방법 A — getUpdates (봇 토큰만 있으면 됨)

1단계 6번에서 봇에게 메시지를 보낸 뒤, 브라우저나 터미널에서:

curl -s "https://api.telegram.org/bot<여기에_봇토큰>/getUpdates"

응답 JSON에서 result[].message.chat.id 값이 내 chat_id다.

{
  "ok": true,
  "result": [
    { "message": { "chat": { "id": 8952171082, "type": "private", ... } } }
  ]
}

응답이 "result": [] 로 비어 있으면 → 봇에게 메시지를 아직 안 보낸 것. 1:1 대화에서 아무거나 보낸 뒤 다시 호출.

방법 B — 헬퍼 봇

텔레그램에서 @userinfobot 또는 @RawDataBot에게 메시지를 보내면 내 숫자 ID를 바로 알려준다.

3단계 · 비밀 파일 만들기

토큰을 MCP 설정 파일에 직접 적지 않으려면(권장), 토큰·chat_id를 담은 비밀 파일 하나를 만든다. 경로는 자유 (예: ~/.config/telegram-ask/secrets.env).

mkdir -p ~/.config/telegram-ask
cat > ~/.config/telegram-ask/secrets.env <<'EOF'
TELEGRAM_BOT_TOKEN=8383648698:AAH...xyz
TELEGRAM_CHAT_ID=8952171082
EOF
chmod 600 ~/.config/telegram-ask/secrets.env   # 본인만 읽기

형식은 KEY=VALUE 또는 export KEY="VALUE" 라인이면 된다 — 일반 쉘 스크립트도 그대로 OK. 이 파일을 git에 커밋하지 말 것(.gitignore에 추가).

토큰을 파일로 빼지 않고 클라이언트 설정에 직접 적어도 된다(환경변수 참고). 다만 평문 노출 위험이 커진다.

4단계 · 설치

깃에서 바로 설치:

uv tool install git+https://github.com/naryeo628/telegram-ask-mcp

또는 클론 후 설치:

git clone https://github.com/naryeo628/telegram-ask-mcp
cd telegram-ask-mcp
uv tool install .

성공하면 실행 파일이 생긴다 → ~/.local/bin/telegram-ask-mcp (경로 확인: which telegram-ask-mcp)

5단계 · MCP 클라이언트에 등록

<you>는 본인 홈 경로로, 비밀 파일 경로는 3단계에서 만든 것으로 바꾼다.

Claude Code (~/.claude.json, user 스코프)

{
  "mcpServers": {
    "telegram-ask": {
      "command": "/Users/<you>/.local/bin/telegram-ask-mcp",
      "args": [],
      "env": {
        "TELEGRAM_ENV_FILE": "/Users/<you>/.config/telegram-ask/secrets.env"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)

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

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

같은 mcpServers 블록을 넣으면 된다(위와 동일).

Cursor 등 다른 MCP 클라이언트

mcpServers에 command/args/env를 받는 클라이언트면 동일한 형식으로 등록 가능 (~/.cursor/mcp.json 등).

등록 후 클라이언트를 재시작해야 도구가 로드된다.

6단계 · 연결 확인

클라이언트 재시작 후, Claude에게 check_config 도구를 실행시킨다(또는 직접 호출). 정상이면:

{
  "ok": true,
  "bot_username": "my_claude_asker_bot",
  "bot_id": 8383648698,
  "chat_id": "8952171082",
  "wait_sec": 600,
  "poll_sec": 50
}

→ 토큰·chat_id가 잘 잡혔고 봇이 살아있다는 뜻. 이제 ask_via_telegram을 쓰면 폰으로 질문이 온다. (토큰 값 자체는 절대 출력하지 않는다.)

"항상 텔레그램으로 묻기" 규칙

Claude가 선택지를 물 상황마다 자동으로 이 도구를 쓰게 하려면, 유저/프로젝트 메모리나 CLAUDE.md에 규칙을 적어 둔다:

사용자에게 선택지를 물어야 할 때는 터미널 팝업 대신 telegram-ask 의
ask_via_telegram 를 먼저 호출한다. timeout 이 오면 그때 터미널에서 다시 묻는다.

규칙 없이 "이건 텔레그램으로 물어봐"라고 그때그때 시켜도 된다.

도구 레퍼런스

ask_via_telegram(question, options=[], allow_free_text=True)

질문을 텔레그램으로 보내고 답을 받을 때까지 기다린다(long-poll).

반환 (답한 경우)

{ "ok": true, "answered": true, "answer": "카나리",
  "via": "button", "option_index": 1, "is_custom": false }

• via: "button"(버튼 탭) 또는 "text"(번호/자유 입력)

• option_index: 선택지를 고른 경우 0-based 인덱스, 자유 답이면 null

• is_custom: 선택지에 없는 자유 답이면 true

반환 (시간 초과)

{ "ok": true, "answered": false, "timeout": true, "waited_sec": 600 }

답하는 법(폰): 버튼을 누르거나, 선택지 번호(2)를 보내거나, 그냥 원하는 답을 입력하면 된다.

notify_telegram(text)

답을 기다리지 않는 단방향 알림. 작업 완료·승인 요청 안내 등. 반환: { "ok": true, "message_id": 123 }

check_config()

봇 연결(getMe)·대상 chat_id·대기 설정을 점검. 토큰 값은 노출하지 않는다.

환경변수

토큰/chat_id는 리터럴 → 개별 파일 → 공유 env 파일 순으로 먼저 잡히는 값을 쓴다. 세 방식 중 하나로만 주입하면 된다 (토큰은 토큰대로, chat_id는 chat_id대로 서로 다른 소스여도 됨).

TELEGRAM_ENV_FILE 값은 서버 시작 시 1회 읽어 캐시한다 — 파일을 바꿨으면 서버(클라이언트)를 재시작.

문제 해결

보안

• 봇 토큰은 MCP 클라이언트 env(또는 비밀 파일)로만 주입. 레포·문서·로그·프론트에 절대 노출 금지.

• 비밀 파일은 chmod 600 + .gitignore. 노출 의심 시 BotFather /revoke로 즉시 재발급.

• getUpdates는 한 번에 하나의 소비자만 받는다. 같은 봇으로 여러 인스턴스를 동시에 long-poll 하면 서로 업데이트를 가로챈다 → 단일 사용자 · 단일 인스턴스 로컬 환경을 전제로 설계됨. 여러 머신/세션에서 쓰려면 봇을 분리하는 것을 권장.

개발 · 재배포

git clone https://github.com/naryeo628/telegram-ask-mcp
cd telegram-ask-mcp
# 소스 수정 후 ...
# pyproject.toml 의 version 을 올린다 (uv 가 동일 버전 캐시 휠을 재사용하므로 필수)
uv tool install . --reinstall --no-cache
# 클라이언트(Claude 등) 재시작 → 새 서버 프로세스 로드

구조: src/telegram_ask/{config,telegram,server}.py

• config.py — 토큰/chat_id 해석(3경로), 대기 설정

• telegram.py — Bot API 얇은 클라이언트(표준 라이브러리만)

• server.py — FastMCP 도구 3종 + ask long-poll 루프

라이선스

MIT