Telegram + Claude tool_use로 개인+회사 캘린더, Notion, Sheets를 한 메시지로 다루는 1인용 비서를 만들었습니다.
핵심 단계는 세 가지입니다.
BotFather로 Telegram 봇 생성 → Claude tool_use 스키마 설계 → Google·Notion API 연결.
도구 description을 구체적으로 다듬는 것이 정확도를 가르는 분기점입니다.
매일 아침 Google Calendar 두 개를 따로 열고, Notion에 할일을 업데이트하고, Slack 스레드를 뒤지는 루틴이 반복됐습니다.
앱 전환 자체가 장벽이었고, 결국 기록은 머릿속에 남거나 사라졌습니다.
그래서 Telegram 한 줄로 모든 입력을 처리하는 1인용 비서를 직접 만들었습니다. 지금은 아침 브리핑부터 Notion CRUD까지 메신저 한 곳에서 끝납니다.
왜 직접 만들었나
문제는 두 갈래였습니다.
첫째, 할일 메모가 흩어졌습니다. Notion, 메모장, Slack, 머릿속이 따로 놀다 보니 뭘 어디에 적었는지 매번 헷갈렸습니다. 기록했지만 잃어버리는 상황이 반복됐습니다.
둘째, Notion이나 Sheets를 열어서 필드를 클릭하는 접근 자체가 귀찮음이었습니다. 업데이트를 미루다 결국 임박해서 처리하는 습관들이 생기기 시작했습니다.
거기에 개인 Google Calendar와 회사 Calendar를 두 군데서 조합하는 아침 루틴이 매일 붙었습니다.
입력의 분절이 생기면 시스템이 아무리 좋아도 사람이 먼저 포기합니다. 다양한 SaaS들이 통합하는 이유이기도 합니다.
그래서 저는 도구를 바꾸는 게 아니라, 입력 경로 자체를 단일화하는 게 답이라는 판단이 섰습니다.
준비물
따라하기 위한 항목은 아래와 같습니다.
- Telegram 계정 + BotFather 접근 권한 (봇 토큰 발급용).
- Anthropic API 계정 — Claude Haiku 4.5 기준, 토큰 단가가 낮아 시제품에 부담이 없습니다.
- Google Cloud 프로젝트 — Calendar API와 Sheets API를 활성화하고 OAuth 2.0 자격증명을 발급해야 합니다.
- Notion API integration token — 연결할 데이터베이스의 integration 공유 설정 필요.
- Python 3.11 환경, python-telegram-bot, anthropic, google-api-python-client 패키지.
- Railway 또는 동급 PaaS 계정 (로컬 실행도 가능하지만 브리핑 스케줄러를 24시간 돌리려면 배포가 필요합니다).
1. Telegram 봇 생성하고 메시지 수신 루프 구성하기
BotFather에서 /newbot 명령으로 봇을 만들고 토큰을 받습니다. 이후 python-telegram-bot으로 메시지를 수신하는 기본 루프를 구성합니다.
핵심은 사용자 입력 텍스트를 그대로 Claude에 넘기는 패스스루 구조를 먼저 만드는 것입니다. 복잡한 전처리 없이 원문을 그대로 전달해야 자연어 파싱 정확도가 유지됩니다.
from telegram.ext import ApplicationBuilder, MessageHandler, filters
async def handle_message(update, context):
user_text = update.message.text # 사용자 입력 원문
# Claude tool_use 호출로 연결 (Step 2에서 구현)
result = await dispatch_to_claude(user_text)
await update.message.reply_text(result)
app = ApplicationBuilder().token("YOUR_BOT_TOKEN").build()
app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, handle_message))
app.run_polling()이 시점에서 봇에게 아무 메시지를 보내면 handle_message가 호출되는지 먼저 확인합니다. 수신 루프가 안정적으로 동작하는 것을 확인한 뒤 다음 단계로 넘어가야 합니다.
2. Claude tool_use 스키마 설계하고 도구 라우팅 구성하기
tool_use의 정확도는 description 품질에 달려 있습니다. 처음에 도구 수를 적게 시작했더니 Claude가 잘못된 도구를 선택하는 경우가 잦았습니다. 도구를 세분화하고 description을 구체적으로 다듬으면서 안정화됐습니다.
예를 들어 “일정 조회”와 “일정 생성”은 반드시 별개 도구로 분리해야 합니다. description에는 트리거 문장 예시를 포함하는 것이 효과적입니다.
tools = [
{
"name": "create_calendar_event",
"description": (
"사용자가 새 일정을 추가하거나 등록하려 할 때 사용. "
"예: '다음 주 목요일 3시 마케팅팀 회의 1시간'. "
"기존 일정 조회나 수정에는 사용하지 않음."
),
"input_schema": {
"type": "object",
"properties": {
"title": {"type": "string"},
"start_datetime": {"type": "string", "description": "ISO 8601"},
"duration_minutes": {"type": "integer"},
"calendar": {"type": "string", "enum": ["personal", "work"]}
},
"required": ["title", "start_datetime", "duration_minutes"]
}
}
# 나머지 도구들을 동일 패턴으로 추가
]Haiku 4.5를 기본으로 쓰고, “다음 주 일정 전체 요약해줘” 같은 복합 추론 요청은 키워드 기반으로 Sonnet으로 라우팅하는 구조가 비용 효율적입니다.
3. Google Calendar·Notion API 연결하고 아침 브리핑 스케줄러 붙이기
Claude가 tool_use로 create_calendar_event를 선택하면, 실제 API를 호출하는 실행 레이어가 필요합니다. 개인 계정과 회사 계정은 OAuth credential을 각각 따로 관리해야 합니다.
from googleapiclient.discovery import build
def create_event(creds, title, start_dt, duration_min):
service = build("calendar", "v3", credentials=creds)
end_dt = start_dt + timedelta(minutes=duration_min)
event = {
"summary": title,
"start": {"dateTime": start_dt.isoformat(), "timeZone": "Asia/Seoul"},
"end": {"dateTime": end_dt.isoformat(), "timeZone": "Asia/Seoul"},
}
return service.events().insert(calendarId="primary", body=event).execute()아침 브리핑은 APScheduler로 매일 7시에 개인+회사 캘린더 이벤트, Open-Meteo 날씨, Notion 할일을 한 메시지로 묶어 Telegram으로 푸시합니다. Open-Meteo는 API 키 없이 사용 가능해서 초기 세팅 부담이 없습니다.
Railway에 배포하면 로컬 머신을 켜두지 않아도 스케줄러가 유지됩니다. 환경변수로 토큰과 credential을 관리하는 것이 기본입니다.
Telegram 으로 자연어 명령을 받아 Google Calendar(개인+회사) / Notion / Sheets 를 다루는 1인용 비서를 만들고 싶습니다.
기술 스택: Python 3.11, python-telegram-bot, anthropic SDK(Claude Haiku 4.5 기본 + 키워드 분기로 Sonnet 4.6 라우팅), google-api-python-client, APScheduler.
환경 변수: TELEGRAM_BOT_TOKEN, ANTHROPIC_API_KEY, GOOGLE_OAUTH_CREDENTIALS_PATH, NOTION_TOKEN.
다음 순서로 단계별로 함께 만들어 주세요. 각 단계마다 검증 명령을 함께 알려 주세요.
1단계: BotFather 토큰을 환경 변수로 관리하고 python-telegram-bot 비동기 수신 루프 구성. 받은 메시지를 그대로 echo. 검증: 봇에 메시지 보내면 echo 응답 확인.
2단계: echo 를 Claude tool_use 호출로 교체. create_calendar_event 도구 1개부터 정의(description 안에 "다음 주 목요일 3시 마케팅팀 회의 1시간" 같은 트리거 문장 예시 포함). 검증: 자연어 일정 명령 → tool_use 응답 확인.
3단계: Google Calendar API 실행 레이어 + APScheduler 로 매일 아침 7시(Asia/Seoul) 개인+회사 일정 요약 푸시. 검증: 자연어 명령으로 실제 캘린더 등록 + 다음날 7시 푸시 수신.마무리
먼저 두 가지만 해보시길 권합니다.
BotFather로 봇 토큰을 발급받고, Claude tool_use로 날씨 조회 도구 하나만 연결해서 자연어 입력 → 도구 호출 한 사이클을 완성하는 것. 이 사이클을 한 번 통과하면 “내 워크플로우에서 어떤 입력 마찰을 없앨 수 있을까”가 자연스럽게 보입니다.
Notion이든 캘린더든, 열기 귀찮아서 안 하게 되는 도구가 있다면 그게 다음 tool의 후보입니다. 🙂
MVP 세팅에 필요한 마스터 프롬포트를 정리해두었습니다:) 복사하셔서 활용해보시면 좋을 것 같습니다.