Cursor IDE와 텔레그램 연동 (MCP)

• Cursor 에이전트가 MCP 도구로 텔레그램 봇 메시지를 보내는 구성이다
• 토큰은 mcp.json 이 아니라 envFile 로 분리해서 Git 에 안 올린다
• 보내기만 되고, 받아서 읽는 건 getUpdates 나 웹훅을 따로 붙여야 한다

연동이라는 말의 뜻

MCP(Model Context Protocol) 는 Cursor 같은 LLM 호스트에 외부 도구와 데이터를 붙이는 표준 방식이다. npx 로 뜨는 MCP 서버 프로세스가 도구를 등록하고, 보통 stdio 나 HTTP 로 호스트와 통신한다.

연동한다고 Cursor 화면이 텔레그램처럼 바뀌는 건 아니다. 에이전트가 MCP 도구를 부르면 서버가 봇 토큰으로 Telegram 에 HTTP 요청을 보내고 메시지가 간다. Cursor 안에서 말하면, 승인 뒤 도구가 실행되고, 텔레그램으로 발송되는 순서다.

동작 흐름

Cursor 가 mcp.json 의 command 와 args 로 MCP 서버를 띄우고, 서버는 도구 목록을 Cursor 에 알려준다. 에이전트가 작업에 맞다고 판단하면 도구 호출을 제안하고, 승인하면 서버가 Telegram API 를 부른다. TELEGRAM_BOT_TOKEN 같은 값은 env 나 envFile 로 프로세스에 넣는다.

MCP 서버는 내 맥에서 코드가 돌고 네트워크로 나갈 수 있다. 믿을 수 있는 패키지만 쓰고, 토큰은 레포, 스크린샷, 공개 페이지에 남기지 않는다.

내가 쓴 구성

패키지는 @harnyk/telegram-notifier-mcp 다. npx -y 로 바로 띄울 수 있고, 환경 변수는 TELEGRAM_BOT_TOKEN 과 TELEGRAM_CHAT_ID 두 개다. 보내기와 알림 중심이라 처음 연결해 보고 테스트하기에 좋다. 사용자 메시지를 받아 읽는 건 getUpdates 폴링이나 웹훅을 따로 구성해야 한다.

설정은 전역 ~/.cursor/mcp.json 에 두고, 비밀 값은 ~/.cursor/telegram-mcp.env 로 따로 뺐다. 프로젝트에서만 쓰려면 레포 루트의 .cursor/mcp.json 에 넣어도 된다.

{
  "mcpServers": {
    "telegram-notifier": {
      "command": "npx",
      "args": ["-y", "@harnyk/telegram-notifier-mcp"],
      "envFile": "${userHome}/.cursor/telegram-mcp.env"
    }
  }
}

${userHome} 은 Cursor 가 홈 경로로 바꿔 주는 변수다. envFile 은 stdio 서버에서만 되고 HTTP 나 SSE 서버에서는 안 된다. 셸 환경 변수를 읽고 싶으면 ${env:이름} 을 쓴다.

# BotFather 토큰
TELEGRAM_BOT_TOKEN=

# 채팅 또는 채널 ID (채널은 음수인 경우가 많다)
TELEGRAM_CHAT_ID=

등호 뒤에는 공백 없이 붙인다. 도구 이름은 패키지 버전에 따라 바뀔 수 있어서 Cursor 의 Available Tools 목록을 기준으로 본다. 텍스트, 사진, 문서, 동영상 같은 걸 보낼 수 있다.

연결 순서

텔레그램에서 @BotFather 를 열고 /newbot 으로 봇을 만든 뒤 나온 HTTP API 토큰을 복사해 둔다.

방금 만든 봇에게 아무 말이나 DM 을 한 통 보낸다. 그다음 브라우저에서 api.telegram.org/bot<TOKEN>/getUpdates 를 열면 JSON 이 나오는데, message.chat.id 가 TELEGRAM_CHAT_ID 다. 채널은 봇을 관리자로 넣고 메시지를 하나 올린 뒤 같은 방법으로 확인하는데, 보통 음수다.

~/.cursor/telegram-mcp.env 에 두 값을 채우고, mcp.json 에 telegram-notifier, npx, envFile 이 들어 있는지 확인한다. Cursor 를 완전히 종료했다 다시 켜고, 설정의 MCP 메뉴에서 telegram-notifier 가 켜져 있는지 본다.

마지막으로 에이전트 채팅에 텔레그램으로 연결 테스트라고 보내 달라고 하고, 승인 창이 뜨면 승인해서 메시지가 오는지 본다.

안 될 때

View → Output 에서 MCP Logs 를 먼저 본다. 토큰이나 채팅 ID 오타가 제일 흔하고, 봇에게 첫 메시지를 안 보내면 getUpdates 에 채팅이 아예 안 뜬다.

슬랙이나 디스코드도 MCP 서버 항목만 하나 더 추가하면 같은 패턴으로 붙일 수 있다. 외부에서 Cursor 에이전트를 부르는 반대 방향을 만들 때는 Cursor 대시보드의 Integrations 에서 API 키를 발급받는다.