telegram-ask-mcp
Enables sending questions and receiving answers via Telegram bots, allowing users to respond to Claude's prompts remotely from their phone.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@telegram-ask-mcpAsk which deployment strategy to use: blue-green, canary, or rolling"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
telegram-ask-mcp
Claude(Claude Code 등)가 선택지를 물어야 할 때 터미널 팝업 대신 텔레그램으로 질문을 보내고, 사용자가 폰에서 누른 버튼·번호·자유 텍스트를 답으로 받아오는 MCP 서버.
자리에 없어도 폰으로 Claude의 질문에 답하고 작업을 계속 진행시킬 수 있다.
🧩 MCP 서버(stdio) · Python
FastMCP· 외부 의존성 없음(표준 라이브러리 +mcp)
┌────────────────────────────────────────┐
│ ❓ 어느 방식으로 배포할까요? │
│ │
│ 1. 블루-그린 │
│ 2. 카나리 │
│ 3. 롤링 │
│ │
│ 👉 버튼을 누르거나 번호를 보내세요. │
│ [ 1. 블루-그린 ] │
│ [ 2. 카나리 ] │
│ [ 3. 롤링 ] │
└────────────────────────────────────────┘
나: 2 ↩목차
Related MCP server: tsgram-mcp
동작 방식
Claude가
ask_via_telegram(question, options)도구를 호출서버가 텔레그램으로 질문 + 번호 인라인 버튼을 전송
사용자가 버튼 탭 / 번호 입력 / 자유 텍스트 중 하나로 응답
서버가
getUpdateslong-poll로 응답을 받아 Claude에 반환약 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가 발급한다.
텔레그램에서
@BotFather검색 → 대화 열기 → Start/newbot입력봇 이름(name) 입력 — 표시용. 아무거나 (예:
My Claude Asker)봇 username 입력 — 반드시
bot으로 끝나야 함, 전역에서 유일해야 함 (예:my_claude_asker_bot)성공하면 BotFather가 토큰을 준다. 이렇게 생긴 문자열:
8383648698:AAH...(생략)...xyz🔐 이 토큰은 비밀번호와 동급. 노출되면 누구나 이 봇을 조종할 수 있다. 채팅·코드·캡처에 남기지 말 것. 잃어버리거나 노출되면 BotFather에서
/token(재확인) 또는/revoke(재발급).방금 만든 봇과의 대화를 열고 아무 메시지나 한 번 보낸다 (예:
/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.jsonWindows:
%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 인덱스, 자유 답이면nullis_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대로 서로 다른 소스여도 됨).
변수 | 기본 | 설명 |
| — | (1) 봇 토큰 리터럴. 비밀 |
| — | (1) 대상 chat_id 리터럴 |
| — | (2) 토큰 원문 1줄이 든 파일 경로 |
| — | (2) chat_id 원문 1줄 파일 경로 |
| — | (3) |
|
| 전체 응답 대기 한도(초) |
|
| 1회 long-poll 길이(초) |
TELEGRAM_ENV_FILE값은 서버 시작 시 1회 읽어 캐시한다 — 파일을 바꿨으면 서버(클라이언트)를 재시작.
문제 해결
증상 | 원인 / 해결 |
| env 미주입 또는 파일 경로 오타. |
질문이 폰으로 안 온다 | 봇과 1:1 대화에서 먼저 메시지를 보냈는지 확인(1단계 6번). 봇은 사용자가 먼저 말 걸기 전엔 발송 불가 |
| 위와 동일 — 봇에게 메시지를 보낸 적이 없음 |
답을 보냈는데 반영이 안 됨 | 같은 봇으로 여러 인스턴스가 동시에 long-poll 중인지 확인. |
코드를 고쳤는데 옛 동작 그대로 |
|
chat_id를 모르겠다 | 2단계 방법 A/B |
보안
봇 토큰은 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
Available Tools
3 toolsask_via_telegramA
텔레그램으로 질문을 보내고 사용자의 답을 받을 때까지 기다린다(long-poll).
사용자가 선택지를 골라야 하는 상황이면 터미널 팝업 대신 이 도구를 쓴다. options 를 주면 번호 버튼으로 표시되고, allow_free_text=True 면 버튼 외 자유 입력도 받는다. options 가 비어 있으면 순수 주관식 질문이 된다.
반환: 답함: {ok, answered:true, answer, via:"button"|"text", option_index: int|None, is_custom: bool} 시간초과: {ok, answered:false, timeout:true, waited_sec} → timeout 이면 Claude 는 평소처럼 터미널에서 다시 물어보면 된다.
| Name | Required | Description | Default |
|---|---|---|---|
| options | No | ||
| question | Yes | ||
| allow_free_text | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the long-poll waiting behavior, possible timeout, and instructions on timeout recovery. It also describes the return structure in detail, including fields like 'answered', 'timeout', 'via', etc. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise for the amount of information given, with a clear structure separating purpose, usage, and return values. It uses bullet points effectively. Slightly verbose in parts but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description thoroughly explains return values and types. It covers behavioral nuances (long-poll, timeout), parameter combinations, and error handling. For a tool with 3 parameters, it provides complete contextual information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add meaning. It explains that 'options' are displayed as numbered buttons, 'allow_free_text' permits free input alongside buttons, and 'question' is the prompt. It also clarifies behavior when options is empty. This fully compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool sends a question via Telegram and waits for a reply (long-poll). It distinguishes itself from sibling 'notify_telegram' by being interactive and waiting for user input, and from 'check_config' by being unrelated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: when the user needs to choose from options instead of a terminal popup. It also explains how to use options and free text, but does not explicitly mention when not to use. However, the guidance is clear and practical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
check_configA
설정 점검: 봇 연결(getMe)과 대상 chat_id 를 확인한다(토큰 값은 노출하지 않음).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description discloses that token values are not exposed, showing safety awareness. It implies a read-only check, though not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that front-loads the purpose ('설정 점검') and efficiently conveys all necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description provides sufficient context about the tool's function and a key behavioral detail (no token exposure). Lacks only explicit read-only or idempotency hints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; schema coverage is 100%. The description adds no parameter meaning because none are needed, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks bot connection (getMe) and target chat_id, distinguishing it from sibling tools that send messages. It specifies the scope without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for verifying configuration before sending messages but does not explicitly state when to use this versus siblings or provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
notify_telegramA
답을 기다리지 않고 텔레그램으로 알림만 보낸다(작업 완료/승인요청 안내 등).
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the key behavior (no waiting for reply), but lacks details on rate limits, delivery guarantees, or error handling. Adequate for a simple notification tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence covers purpose, behavior, and examples with zero waste. Information is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers purpose, use cases, and key behavior. It lacks mention of return value, but this is minor given tool simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single 'text' parameter is implied by the description, but no additional meaning is added beyond the schema field name. Schema coverage is 0%, but the description's examples partially compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (send notification) and resource (Telegram), and explicitly distinguishes from 'ask_via_telegram' by noting no reply is expected. Examples of use cases (task completion, approval request) further clarify purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (send notifications without reply) via examples, and contrasts with the sibling 'ask_via_telegram'. However, it does not explicitly state when not to use or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
3 tool updates
v0.1.1- First observed
ask_via_telegram - First observed
check_config - First observed
notify_telegram
TDQS
Scored across 3 tools
Each tool serves a distinct purpose: ask_via_telegram handles interactive questions with answers, notify_telegram sends one-way notifications, and check_config validates configuration. No functional overlap.
All tool names use a verb-first pattern with underscores (ask_via_telegram, check_config, notify_telegram). The first tool includes 'via_telegram' while the others just use 'telegram', which is a minor inconsistency but still predictable.
Three tools is slightly below average but appropriate for the focused scope of asking questions and sending notifications via Telegram. The set is not bloated and each tool is essential.
The tool set covers core operations for Telegram interaction: asking, notifying, and checking configuration. Missing capabilities like media sending or message editing, but these are not essential for the primary use case.
Maintenance
Related MCP Connectors
Share context and questions between Claude instances — VS Code, claude.ai web, and mobile.
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Run a Telegram channel from your AI agent. Posts go out through your own bot, not your account.
WHOOP recovery, strain, sleep and workouts in Claude via official WHOOP OAuth. Free, open source.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables Claude Code to send Telegram notifications when tasks complete, errors occur, or user intervention is needed. Runs serverless on Cloudflare Workers with support for formatted messages and flexible chat targeting.7 npm22MIT
- AlicenseNot gradedqualityDmaintenanceConnects Claude Code sessions to Telegram, enabling AI-powered code assistance and file management directly from Telegram chats.89MIT
- AlicenseAqualityCmaintenanceEnables Claude Code to send and receive messages via Telegram for remote interaction and approval of sensitive operations.86 npm7MIT
- FlicenseNot gradedqualityDmaintenanceEnables Claude Code to send messages to and receive instructions from Telegram, with task tracking and persistent storage.-