telegram-team-mcp

MCP server for AI agents to participate in Telegram group chats.

Two ways to use:

1. MCP mode — add to your existing agent, it gets Telegram tools
2. Daemon mode — fully automatic, watches mentions and invokes your agent CLI

Quick Start

1. Create bot + get chat ID

1. @BotFather → /newbot → save token
2. /setprivacy → select bot → Disable
3. Create group, add bot
4. Add @userinfobot to get chat ID (-100...)

2a. MCP mode (add to existing agent)

Your agent keeps all its settings. You just add Telegram tools.

claude mcp add telegram \
  -e TELEGRAM_BOT_TOKEN=7000000000:AAxxxx \
  -e TELEGRAM_CHAT_ID=-100123456789 \
  -- npx -y telegram-team-mcp

Then tell your agent: "Monitor Telegram using wait_for_mentions, respond via send_message."

2b. Daemon mode (fully automatic)

Runs in a terminal tab. Watches for @mentions, invokes your agent CLI per mention. Doesn't touch your agent's model/prompt/permissions — only passes the MCP config and the mention.

TELEGRAM_BOT_TOKEN=7000000000:AAxxxx \
TELEGRAM_CHAT_ID=-100123456789 \
npx telegram-team-mcp --daemon

With custom command:

TELEGRAM_BOT_TOKEN=... \
TELEGRAM_CHAT_ID=... \
AGENT_COMMAND=claude_proxy_dan \
AGENT_EXTRA_ARGS="--dangerously-skip-permissions" \
npx telegram-team-mcp --daemon

The daemon runs: claude_proxy_dan -p "<mention context>" --mcp-config <auto> --dangerously-skip-permissions

Everything else (model, CLAUDE.md, system prompt) comes from your environment.

With Codex:

AGENT_CLI=codex npx telegram-team-mcp --daemon

Runs: codex exec "<mention context>" --full-auto --ephemeral

Environment Variables

| Variable | Required | Description | |---|---|---| | TELEGRAM_BOT_TOKEN | Yes | Bot token from @BotFather | | TELEGRAM_CHAT_ID | Yes | Chat ID(s), comma-separated | | DB_PATH | No | SQLite dir (default: ~/.telegram-team-mcp/) |

Daemon-only:

| Variable | Default | Description | |---|---|---| | AGENT_COMMAND | claude | CLI binary to invoke | | AGENT_EXTRA_ARGS | — | Extra args (space-separated), e.g. --dangerously-skip-permissions | | AGENT_CLI | auto | claude, codex, or custom | | ANNOUNCE_ON_START | false | Send "bot online" message |

MCP Tools

| Tool | Description | |---|---| | wait_for_mentions | Block until @mention arrives (or timeout). For auto-monitoring loops. | | send_message | Send message / reply to the group | | get_new_messages | Messages since a given ID | | get_recent_messages | Last N messages | | search_messages | Full-text search (FTS5) | | get_mentions | Unprocessed @mentions (non-blocking) | | mark_mentions_read | Mark mentions as handled | | get_thread | Reply chain for a message | | get_chat_info | Chat info + stats |

Telegram Commands (daemon mode)

Mention the bot with a command:

| Command | Description | |---|---| | @bot /status | Uptime, message count | | @bot /stats | Chat statistics | | @bot /search <query> | Search history | | @bot /clear | Clear pending mentions | | @bot /compact | AI summary of last 50 msgs | | @bot /help | List commands |

Multi-agent Setup

You + friend, each with a bot:

Machine 1: TELEGRAM_BOT_TOKEN=<your_token> ... npx telegram-team-mcp --daemon
Machine 2: TELEGRAM_BOT_TOKEN=<friend_token> ... npx telegram-team-mcp --daemon

Both watch the same group. Each responds only to its own @mentions.

Notes

• Disable privacy mode via @BotFather → re-add bot to group
• Bots can't read pre-existing messages — history builds over time
• Rate limits: 20 msg/min per group
• One process per bot token (Telegram allows one polling connection)

Development

npm install && npm run dev -- --daemon

License

MIT