클로드코드(Claude Code) 텔레그램 AI 비서 만들기 1편: MCP 서버 하나로 메신저 연결하는 원리 (2026)

클로드코드(Claude Code)를 텔레그램에 연결하는 방법은 봇을 새로 개발하는 게 아니라, MCP(Model Context Protocol) 서버 하나로 텔레그램을 Claude Code의 입출력 채널로 붙이는 거예요. 서버가 텔레그램 봇 API를 2초마다 폴링해서 새 메시지를 MCP notification으로 Claude Code에 넣고, Claude Code는 reply 툴로 답장을 보내요. 별도 서버도, 공인 IP도, webhook도 필요 없고 로컬 PC만 켜져 있으면 돼요.

저는 가상자산 거래소에서 데이터 분석과 사업 기획을 하면서, 개인용 AI 비서 “tede”를 직접 만들어 매일 쓰고 있어요. 이 시리즈는 상용 솔루션 소개가 아니라 제작기라서, 잘 된 부분만큼 막혔던 부분도 같이 적었어요.

이 글에서 다루는 내용

• 터미널 없이 메신저로 AI 코딩 에이전트를 부리는 구조가 왜 가능한지
• Claude Code와 텔레그램의 정확한 연결 지점 (코드 79줄의 정체)
• 여러 프로젝트를 비서 하나가 라우팅하는 오케스트레이터 개념

왜 메신저로 AI 비서를 만들었나요?

이유는 두 가지예요. 첫째, 아이디어는 출근길, 자기 직전, 밥 먹다가도 튀어나오는데, 그때마다 받아 적어 주고 간단하게라도 바로 구현해 주는 AI 에이전트가 필요했어요. 둘째, 터미널 앞에 묶여 있는 게 싫었어요. AI 코딩 에이전트를 제대로 쓰려면 검은 화면 앞에서 명령을 넣고 결과를 보는 일을 반복해야 하는데, 자리를 뜨는 순간 아무것도 못 하거든요.

그래서 방향을 뒤집었어요. 내가 AI한테 가는 게 아니라 AI가 나한테 오게, 이미 하루 종일 손에 쥐고 있는 메신저를 AI의 창구로 만들었어요. 지금은 회사 일, 개인 일, 떠오른 아이디어를 구분하지 않고 한 대화창에서 얘기하면 tede가 받아내고, 필요하면 알아서 프로젝트를 만들어요. 프로젝트별 세팅이나 세션 관리를 제가 따로 하지 않아요. 창구도 대화도 하나인데, 속에서는 일이 알아서 쪼개지는 구조예요.

무엇을 만들었나요? “나를 위한 1인 회사”

만들고 나서 느낀 걸 한마디로 하면, 저를 위한 1인 회사를 운영하는 느낌이에요. 맨 위에 CEO 격인 비서(tede)가 있고, 그 아래 트레이딩, 앱, 뉴스 수집, 시장 분석 같은 사업부가 있어요. 각 사업부 안에는 다시 개발, QA, 마케팅, 리스크 관리 팀이 있고요. 저는 CEO에게 말만 걸면 나머지 위임은 안에서 굴러가요.

핵심 성격은 얇은 오케스트레이터예요. tede가 직접 코딩하지 않고, 요청을 이해해서 적절한 담당에게 넘기고 결과를 정리해서 저에게 돌려주는 역할만 해요.

구성	역할
메신저 채널	텔레그램으로 지시와 보고 (터미널 대체)
오케스트레이터 (tede)	요청 의도 파악, 담당에게 위임, 결과 정리
프로젝트 CEO들	사업부 단위로 실제 작업 수행 (프로젝트별 독립)
팀 (개발, QA, 마케팅, 리스크)	사업부 안에서 세부 작업
메모리	세션이 끊겨도 유지되는 파일 기반 기억

일반 챗봇과의 차이가 여기 있어요. 봇 하나가 답하는 게 아니라 비서가 받아서 담당에게 넘기는 위임 구조라서, 회사 일부터 개인 아이디어까지 결이 다른 일을 창구 하나로 소화해요.

텔레그램은 어떻게 연결하나요?

가장 많이 받는 질문이에요. 결론은 “봇을 만드는 게 아니라 채널을 붙인다”예요. Claude Code를 텔레그램 봇으로 개조하는 게 아니라, 텔레그램을 Claude Code의 입출력 채널로 연결해요. 원리는 MCP 서버 하나이고, 두 방향으로 움직여요.

들어오는 방향 (텔레그램에서 AI로)

1. 텔레그램 봇 API를 2초마다 폴링해서 새 메시지를 가져와요
2. 허용된 사용자 ID인지 확인해요 (화이트리스트)
3. 메시지를 MCP notification으로 Claude Code에 밀어 넣어요

나가는 방향 (AI에서 텔레그램으로)

1. Claude Code가 reply 툴을 호출해요
2. MCP 서버가 텔레그램 sendMessage API로 전달해요

이게 전부예요. 코드로 보면 다음과 같아요 (토큰은 마스킹했어요).

const BOT_TOKEN = "8696xxxxxx:AAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"  // 절대 공개 금지
const ALLOWED_USER_IDS = new Set<number>([1234567890])  // 내 텔레그램 ID만

// 나가는 방향: Claude가 이 툴을 부르면 텔레그램으로 전송
mcp.setRequestHandler(CallToolRequestSchema, async req => {
  if (req.params.name === 'reply') {
    const { chat_id, text } = req.params.arguments
    const res = await fetch(`https://api.telegram.org/bot${BOT_TOKEN}/sendMessage`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ chat_id, text }),
    })
    // ... 실패 시 성공으로 위장하지 않고 에러를 그대로 올림
  }
})

// 들어오는 방향: 2초마다 새 메시지를 폴링
setInterval(async () => {
  const res = await fetch(`https://api.telegram.org/bot${BOT_TOKEN}/getUpdates?offset=${offset}&timeout=10`)
  const data = await res.json()
  for (const update of data.result ?? []) {
    const msg = update.message
    if (!msg || !ALLOWED_USER_IDS.has(msg.from.id)) continue  // 화이트리스트 검문
    await mcp.notification({
      method: 'notifications/claude/channel',
      params: { content: msg.text, meta: { chat_id: String(msg.chat.id) } },
    })
  }
}, 2000)

기억할 부분은 두 줄이에요.

• notifications/claude/channel: 이 notification이 텔레그램 메시지를 Claude의 대화에 주입해요
• ALLOWED_USER_IDS: 이게 없으면 봇 링크를 아는 누구나 내 AI에게 명령할 수 있어요. 보안의 최소선이에요

보안에서 꼭 지킬 3가지는?

직접 만들 때 가장 자주 실수하는 부분이라 따로 뺐어요.

1. 봇 토큰을 코드에 하드코딩하지 않기: GitHub에 올리는 순간 남이 봇을 탈취해요. 반드시 환경변수로 분리하세요
2. 사용자 화이트리스트 필수: 텔레그램 봇은 기본적으로 누구나 말을 걸 수 있어요. from.id 검문이 없으면 그냥 공개 API가 돼요
3. 전송 실패를 성공으로 위장하지 않기: 텔레그램은 4096자 초과 같은 상황에서 조용히 실패해요. “보냄”이라고 응답해도 실제로는 도착하지 않은 경우가 생기니, API 응답의 ok를 꼭 확인하세요

자주 묻는 질문

Q. 서버가 꼭 있어야 하나요?
아니에요, 로컬 PC에서 도는 스크립트예요. 폴링 방식이라 공인 IP도 webhook도 필요 없고, PC만 켜져 있으면 돼요.

Q. 카카오톡으로도 되나요?
원리는 같아요. 다만 카카오는 개인 계정 자동화 정책이 텔레그램보다 까다로워요. 텔레그램 봇 API가 진입장벽이 가장 낮아요.

Q. 왜 MCP인가요? 그냥 봇으로 짜면 안 되나요?
MCP로 붙이면 Claude Code의 모든 능력(파일 작업, 코드 실행, 다른 도구)을 그대로 쓰면서 입출력만 텔레그램으로 바뀌어요. 봇을 따로 짜면 그 능력을 처음부터 다시 만들어야 해요.

Q. 코딩을 하나도 몰라도 만들 수 있나요?
이 시리즈는 직접 만든 기록이라 코드가 나와요. 다만 요즘은 클로드코드 같은 AI에게 이 글을 그대로 보여주면서 “이렇게 붙여 줘”라고 시키는 방식으로도 충분히 따라올 수 있어요.

따라하기 팩 (무료)

이 글에서 다룬 채널 MCP 서버를 값만 채우면 돌아가는 파일로 정리했어요.

• telegram-channel.ts: 채널 서버 본체 (토큰을 환경변수로 분리한 안전한 버전)
• .env.example: 봇 토큰과 내 ID를 넣는 템플릿
• README.md: 5단계 셋업 가이드 (봇 만들기, ID 확인, MCP 등록)
• package.json, .gitignore

tede_telegram_pack.zip 다운로드

README대로 따라 하면 돼요. 이런 셋업은 README(MD)를 AI에게 통째로 보여주고 “이대로 붙여 줘”라고 하면 훨씬 빨라서, 그렇게 쓰시라고 MD로 정리했어요.

시리즈 다음 편

2편은 여러 프로젝트를 비서 하나가 라우팅하는 방법(projects.yaml과 위임 구조)이에요. 클로드코드 AI 비서 만들기 2편: 프로젝트 라우팅에서 이어져요. 3편에서는 세션이 끊겨도 기억을 유지하는 파일 기반 메모리를 다뤄요.

출처: 본문 코드는 필자가 직접 작성해 운영 중인 MCP 서버에서 발췌해 마스킹한 것이에요. 참고 문서는 MCP 공식 문서(https://modelcontextprotocol.io)와 텔레그램 Bot API(https://core.telegram.org/bots/api)예요.