# 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](https://t.me/BotFather) → `/newbot` → save token
2. `/setprivacy` → select bot → **Disable**
3. Create group, add bot
4. Add [@userinfobot](https://t.me/userinfobot) to get chat ID (`-100...`)

### 2a. MCP mode (add to existing agent)

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

```bash
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.

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

**With custom command:**
```bash
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:**
```bash
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

```bash
npm install && npm run dev -- --daemon
```

## License

MIT