Kiro Telegram MCP

Kiro Telegram MCP is a Model Context Protocol server that connects Kiro to Telegram for community, hackathon, and developer workflow management.

It helps Kiro list selected chats, read recent messages, search live or cached history, summarize conversations, triage unread chats, inspect message context, collect submission links, manage scheduled channel posts, send approved text or media, and turn Telegram feedback into Kiro-ready requirements, design notes, and tasks.

What It Does

• Authenticates a Telegram user account with local session reuse.
• Lists recent Telegram groups, channels, bots, and private chats.
• Shows authenticated account and selected chat metadata.
• Reads recent messages from a selected chat.
• Reads message context, thread replies, media metadata, reactions, and poll results.
• Searches Telegram live through GramJS.
• Syncs selected chat history into a local SQLite cache.
• Searches cached Telegram history without hitting Telegram.
• Extracts project links from GitHub, Vercel, Netlify, YouTube, Drive, Devpost, Figma, and other URLs.
• Exports extracted links as CSV text.
• Computes chat stats and recent activity reports.
• Detects likely unanswered questions.
• Drafts replies without sending them.
• Sends messages and replies only after explicit confirmation.
• Sends or schedules local media files only after explicit confirmation.
• Edits, forwards, pins, unpins, marks read, and sends scheduled messages now with confirmation gates.
• Sends Kiro task completion updates to Telegram after confirmation.
• Converts Telegram feedback into Kiro requirements, design notes, and tasks.
• Lists, creates, reschedules, and deletes scheduled Telegram messages with confirmation gates.

Why I Built This

Kiro supports MCP, but Telegram is often where developer communities, workshops, and hackathons actually run. Important questions, submissions, bug reports, and feedback get buried in fast-moving chats. This MCP gives Kiro controlled access to Telegram so those conversations can become summaries, action items, specs, and safe replies.

Installation

npm install
npm run build

For local development:

npm run dev

For the compiled MCP server:

npm run start

To expose the binary locally:

npm link
kiro-telegram-mcp

Telegram API Setup

1. Go to https://my.telegram.org/auth.
2. Create an app to get TELEGRAM_API_ID and TELEGRAM_API_HASH.
3. Copy .env.example to .env.
4. Fill in:

TELEGRAM_API_ID=123456
TELEGRAM_API_HASH=your_api_hash
TELEGRAM_PHONE_NUMBER=+6512345678
KIRO_TELEGRAM_SAFE_MODE=true

Do not commit .env, session files, or cache files.

Authentication

Run:

npm run auth

The script prompts for your Telegram phone login code and optional 2FA password. It stores a reusable local session at:

~/.kiro-telegram-mcp/session.txt

Reset the session:

npm run reset-session

Kiro MCP Configuration

After npm run build, add this to .kiro/settings/mcp.json or your global Kiro MCP config:

{
  "mcpServers": {
    "telegram-dev": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "TELEGRAM_API_ID": "${TELEGRAM_API_ID}",
        "TELEGRAM_API_HASH": "${TELEGRAM_API_HASH}",
        "TELEGRAM_SESSION_PATH": "${TELEGRAM_SESSION_PATH}",
        "KIRO_TELEGRAM_CACHE_PATH": "${KIRO_TELEGRAM_CACHE_PATH}",
        "KIRO_TELEGRAM_SAFE_MODE": "true"
      }
    }
  }
}

If you use npm link, you can configure:

{
  "mcpServers": {
    "telegram": {
      "command": "kiro-telegram-mcp",
      "env": {
        "TELEGRAM_API_ID": "${TELEGRAM_API_ID}",
        "TELEGRAM_API_HASH": "${TELEGRAM_API_HASH}",
        "KIRO_TELEGRAM_SAFE_MODE": "true"
      }
    }
  }
}

Example Prompts

• List my recent Telegram groups.
• Read the last 50 messages from my hackathon group.
• Search the hackathon group for submission deadline.
• Sync this Telegram chat from the last 7 days.
• Search cached history for all messages about Kiro errors this week.
• Summarize what happened in the AWS SBG Telegram group today.
• Show context around message 1234.
• Get replies, reactions, or poll results for this channel post.
• Triage my unread Telegram messages.
• Show recent activity across my top Telegram chats.
• Find questions in the hackathon group that nobody has replied to.
• Extract all GitHub, Vercel, Netlify, YouTube, and Google Drive links.
• Export all submission links as CSV.
• Draft a reply to the person asking about judging criteria.
• Send a reminder after I confirm the exact text.
• Schedule this channel image and caption for tomorrow morning.
• Move this scheduled channel post to Friday at 9 AM.
• Send this scheduled post now.
• Pin this announcement after I confirm.
• Turn Telegram feedback about Kiro Buddy into requirements, design notes, and tasks.
• Notify me on Telegram when this Kiro task is done.

Safety and Privacy

Telegram access is sensitive, so the defaults are conservative:

• Sessions are stored locally.
• Cache is stored locally in SQLite.
• Message sends require confirm=true.
• Safe mode is enabled by default.
• In safe mode, confirmation_text must exactly match the outgoing text.
• For media sends, safe mode also requires confirmation_file_path to exactly match file_path.
• Optional KIRO_TELEGRAM_ALLOWED_CHAT_IDS limits write tools to selected chats.
• OTP codes and API hashes are not logged by this project.
• Cache and session paths are ignored by git.

Example send preview:

{
  "chat_id": "123456",
  "text": "Reminder: submissions close at 1 AM tonight.",
  "confirm": false
}

Confirmed safe-mode send:

{
  "chat_id": "123456",
  "text": "Reminder: submissions close at 1 AM tonight.",
  "confirm": true,
  "confirmation_text": "Reminder: submissions close at 1 AM tonight."
}

Tool List

• telegram_auth_status
• telegram_get_me
• telegram_list_chats
• telegram_get_chat_info
• telegram_get_messages
• telegram_get_message_context
• telegram_get_thread_replies
• telegram_get_media_metadata
• telegram_get_reactions
• telegram_get_poll_results
• telegram_search_live
• telegram_cache_status
• telegram_sync_chat_cache
• telegram_search_cache
• telegram_clear_cache
• telegram_summarize_chat
• telegram_get_chat_stats
• telegram_get_recent_activity_report
• telegram_triage_unread
• telegram_find_unanswered_questions
• telegram_extract_links
• telegram_export_links_csv
• telegram_draft_reply
• telegram_send_message
• telegram_send_reply
• telegram_send_media
• telegram_schedule_media
• telegram_send_kiro_update
• telegram_edit_message
• telegram_forward_message
• telegram_mark_read
• telegram_pin_message
• telegram_unpin_message
• telegram_get_scheduled_messages
• telegram_schedule_message
• telegram_reschedule_message
• telegram_delete_scheduled_message
• telegram_send_scheduled_now
• telegram_feedback_to_kiro_spec

Troubleshooting

TELEGRAM_API_ID is missing or invalid.

Check .env or the MCP config env block.

Telegram is not authenticated. Run npm run auth first.

Run npm run auth and complete the Telegram login.

Safe mode requires confirmation_text to exactly match the message text.

Copy the final outgoing message into confirmation_text exactly.

Native SQLite install issues on Windows:

This project uses better-sqlite3. If install fails, make sure you are on a current Node LTS/current runtime and rerun npm install.

Roadmap

• Media downloads and image/audio/document processing.
• Optional prompt templates for channel scheduling workflows.
• More Kiro-specific prompt templates.
• Public npm release and demo video.

Contributing

Keep the privacy and safety model intact. Read tools can be broad, but write tools must remain explicit, reviewable, and confirmation-gated.

License

MIT