{"id":35553929,"url":"https://github.com/tuannvm/telegram-mcp-server","last_synced_at":"2026-01-13T20:03:54.072Z","repository":{"id":331744616,"uuid":"1127543018","full_name":"tuannvm/telegram-mcp-server","owner":"tuannvm","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-11T06:16:09.000Z","size":270,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-11T09:25:43.998Z","etag":null,"topics":["mcp","mcp-server","ralph-wiggum","telegram"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tuannvm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-04T05:14:04.000Z","updated_at":"2026-01-11T06:16:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tuannvm/telegram-mcp-server","commit_stats":null,"previous_names":["tuannvm/telegram-mcp-server"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/tuannvm/telegram-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuannvm%2Ftelegram-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuannvm%2Ftelegram-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuannvm%2Ftelegram-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuannvm%2Ftelegram-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tuannvm","download_url":"https://codeload.github.com/tuannvm/telegram-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuannvm%2Ftelegram-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28399514,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","mcp-server","ralph-wiggum","telegram"],"created_at":"2026-01-04T08:14:11.473Z","updated_at":"2026-01-13T20:03:54.066Z","avatar_url":"https://github.com/tuannvm.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Telegram MCP Server\n\n[![npm version](https://img.shields.io/npm/v/@tuannvm/telegram-mcp-server.svg)](https://www.npmjs.com/package/@tuannvm/telegram-mcp-server)\n[![npm downloads](https://img.shields.io/npm/dm/@tuannvm/telegram-mcp-server.svg)](https://www.npmjs.com/package/@tuannvm/telegram-mcp-server)\n[![license](https://img.shields.io/npm/l/@tuannvm/telegram-mcp-server.svg)](https://www.npmjs.com/package/@tuannvm/telegram-mcp-server)\n\nSend Telegram notifications from anywhere — works seamlessly across local machines, remote SSH sessions, and containerized environments.\n\n```mermaid\ngraph LR\n    A[Claude Code] --\u003e B[Telegram MCP Server]\n    B --\u003e C[Telegram Bot API]\n    C --\u003e D[Your Telegram Chat]\n\n    style A fill:#FF6B35\n    style B fill:#4A90E2\n    style C fill:#0088cc\n    style D fill:#00D4AA\n```\n\n## Quick Start\n\n### 1. Create Telegram Bot\n\n```bash\n# Message @BotFather on Telegram\n/newbot\n# Follow prompts to get your bot token\n```\n\n### 2. Add to Claude Code\n\n```bash\nexport TELEGRAM_BOT_TOKEN=\"your-bot-token\"\nexport TELEGRAM_CHAT_ID=\"your-chat-id\"\nclaude mcp add telegram -- npx -y @tuannvm/telegram-mcp-server\n```\n\n### 3. Start Using\n\n```\nSend notification \"✅ DONE\" to \"Deployment complete\"\nSend telegram status to check configuration\n```\n\n## One-Click Install\n\n[![VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square\u0026logo=visualstudiocode\u0026logoColor=white)](https://vscode.dev/redirect/mcp/install?name=telegram\u0026config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22@tuannvm/telegram-mcp-server%22%5D%2C%22env%22%3A%7B%22TELEGRAM_BOT_TOKEN%22%3A%22YOUR_BOT_TOKEN%22%2C%22TELEGRAM_CHAT_ID%22%3A%22YOUR_CHAT_ID%22%7D%7D)\n[![VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square\u0026logo=visualstudiocode\u0026logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=telegram\u0026config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22@tuannvm/telegram-mcp-server%22%5D%2C%22env%22%3A%7B%22TELEGRAM_BOT_TOKEN%22%3A%22YOUR_BOT_TOKEN%22%2C%22TELEGRAM_CHAT_ID%22%3A%22YOUR_CHAT_ID%22%7D%7D)\n[![Cursor](https://img.shields.io/badge/Cursor-Install-00D8FF?style=flat-square\u0026logo=cursor\u0026logoColor=white)](https://cursor.com/en/install-mcp?name=telegram\u0026config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IC15IEB0dWFubnZtL3RlbGVncmFtLW1jcC1zZXJ2ZXIiLCJlbnYiOnsiVEVMRUdSQU1fQk9UX1RPS0VOIjoiWU9VUl9CT1RfVE9LRU4iLCJURUxFR1JBTV9DSEFUX0lEIjoiWU9VUl9DSEFUX0lEIn19)\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `send_telegram` | Send Telegram notifications with HTML formatting |\n| `telegram_status` | Check if Telegram credentials are configured |\n| `send_and_wait` | Send message and optionally poll for replies with progress notifications |\n| `check_replies` | Check for pending replies from Telegram (non-blocking) |\n\n## Examples\n\n**Simple notification:**\n```\nSend notification \"✅ DONE\" to \"Build completed successfully\"\n```\n\n**With context:**\n```\nSend notification \"🚫 BLOCKED\" to \"Need approval to continue\n\n📁 /path/to/project\n🌿 Branch: feature/new-auth\n💻 Host: production-server\n\nTask: Deploying to production\nIssue: Requires manual approval\"\n```\n\n**Error reporting:**\n```\nSend notification \"❌ ERROR\" to \"Deployment failed\n\nError: Database connection timeout\nExit code: 1\nDuration: 45s\"\n```\n\n**Status check:**\n```\nSend telegram status to verify configuration\n```\n\n**Send and wait for reply:**\n```\nUse send_and_wait to send \"Deploy to production?\" with waitForReply=true and timeout=300\n```\n\n**Check for replies:**\n```\nUse check_replies to see if user responded to pending messages\n```\n\n## Getting Your Chat ID\n\n```bash\n# After creating your bot, send a message to it\n# Then visit this URL in your browser:\nhttps://api.telegram.org/bot\u003cYOUR_BOT_TOKEN\u003e/getUpdates\n\n# Look for \"chat\":{\"id\":123456789} in the response\n```\n\n## Requirements\n\n- **Telegram Bot Token** — Create a bot via @BotFather on Telegram\n- **Telegram Chat ID** — Your personal Telegram chat ID or group ID\n- **Node.js 18+** — For local development\n\n## Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `TELEGRAM_BOT_TOKEN` | Your Telegram bot token from @BotFather | Yes |\n| `TELEGRAM_CHAT_ID` | Target chat ID for notifications | Yes |\n\n## Development\n\n```bash\nnpm install    # Install dependencies\nnpm run dev    # Development mode\nnpm run build  # Build for production\nnpm test       # Run tests\nnpm run lint   # Run ESLint\n```\n\n## How It Works\n\nThis MCP server runs as a separate process communicating via stdio. When you call `send_telegram`:\n\n1. The MCP server receives the request via stdio\n2. It makes an HTTP request to Telegram's Bot API\n3. Your notification appears instantly on Telegram\n\nThis works reliably across:\n- Local development machines\n- Remote SSH sessions\n- Containerized environments\n- CI/CD pipelines\n\n## Bidirectional Communication\n\nThe server supports polling-based bidirectional communication with Telegram using the getUpdates API:\n\n1. **send_and_wait**: Send a message and poll for replies with progress notifications\n2. **check_replies**: Check for pending replies from Telegram (non-blocking)\n\n### Documentation\n\n- **[Bidirectional Communication Guide](docs/bidirectional-communication.md)** - How to use send_and_wait and check_replies\n- **[Technical Architecture](docs/architecture.md)** - Implementation details and system design\n- **[Usage Examples](docs/usage-examples.md)** - Practical workflows and examples\n\n### State Storage\n\nThe server uses file-based offset tracking for Telegram's getUpdates API:\n\n**Location:** `~/.telegram-mcp-state/offset.json`\n\n**Format:**\n```json\n{\n  \"offset\": 123456\n}\n```\n\nThis stores the last processed `update_id + 1` to ensure no duplicate message processing across server restarts.\n\n### How Polling Works\n\n1. Server calls `getUpdates` API with the stored offset\n2. Telegram returns all new messages/updates since that offset\n3. Server updates the offset after processing each batch\n4. For `send_and_wait`, the server polls continuously until a reply is received or timeout occurs\n\nNo external webhook is required - the server polls directly from Telegram.\n\n## License\n\nISC\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuannvm%2Ftelegram-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftuannvm%2Ftelegram-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuannvm%2Ftelegram-mcp-server/lists"}