# Telegram MCP Server for Claude Code

A bidirectional Telegram bridge that allows [Claude Code](https://docs.anthropic.com/en/docs/claude-code) to communicate with you via Telegram. Built on the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).

## Features

- **Send messages** from Claude Code to your Telegram
- **Receive instructions** — send Telegram messages that Claude Code can read
- **Task tracking** — create, update, and monitor tasks with Telegram notifications
- **Persistent storage** — all messages and tasks stored in SQLite
- **Webhook-based** — no polling, instant message delivery

## Architecture

```
You (Telegram) ←→ Telegram Bot API ←→ Webhook Server (Express, port 3100) ←→ SQLite DB
                                                                                ↕
Claude Code ←→ MCP Server (stdio) ←→ SQLite DB
```

Two processes share the same SQLite database:
- **Webhook Server** — receives your Telegram messages via bot webhook
- **MCP Server** — spawned by Claude Code via stdio, reads/writes the same DB

## Prerequisites

- Node.js 18+
- A Telegram bot (create one via [@BotFather](https://t.me/BotFather))
- Your Telegram chat ID (use [@userinfobot](https://t.me/userinfobot) to find it)
- A publicly accessible URL for the webhook (e.g., via reverse proxy or tunnel)

## Installation

```bash
git clone https://github.com/xmart2k/telegram-mcp.git
cd telegram-mcp
npm install
npm run build
```

## Configuration

Copy the example environment file and fill in your values:

```bash
cp .env.example .env
```

Edit `.env`:

```env
TELEGRAM_BOT_TOKEN=your_bot_token_from_botfather
TELEGRAM_CHAT_ID=your_telegram_chat_id
WEBHOOK_PORT=3100
WEBHOOK_HOST=0.0.0.0
DB_PATH=/path/to/data/telegram-mcp.db
```

## Claude Code Setup

Add the MCP server to your Claude Code configuration (`.mcp.json` in your project or `~/.claude/settings.json` globally):

```json
{
  "mcpServers": {
    "telegram-pm": {
      "command": "node",
      "args": ["/path/to/telegram-mcp/dist/mcp-server.js"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your_bot_token",
        "TELEGRAM_CHAT_ID": "your_chat_id",
        "DB_PATH": "/path/to/telegram-mcp/data/telegram-mcp.db"
      }
    }
  }
}
```

## Running the Webhook Server

Start the webhook server to receive Telegram messages:

```bash
# Development
npm run dev:webhook

# Production
npm run start:webhook
```

### Systemd Service (optional)

For production, install as a systemd service:

```bash
# Edit telegram-webhook.service to match your paths
sudo cp telegram-webhook.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now telegram-webhook
```

### Register the Webhook

After the server is running and accessible via a public URL, register the webhook with Telegram (one-time setup):

```bash
curl -X POST http://localhost:3100/webhook/setup \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-domain.com/webhook"}'
```

Verify webhook status:

```bash
curl http://localhost:3100/webhook/info
```

## MCP Tools

| Tool | Description |
|------|-------------|
| `send_message` | Send a Telegram message to you |
| `get_instructions` | Check for pending messages from you |
| `acknowledge_instruction` | Mark a specific instruction as processed |
| `acknowledge_all_instructions` | Mark all pending instructions as processed |
| `create_task` | Create a tracked task with optional notification |
| `update_task_status` | Update task status with optional notification |
| `get_task_status` | Get status and history of a task |
| `list_active_tasks` | List all non-completed tasks |
| `list_all_tasks` | List all tasks including completed |

## Usage Examples

Once configured, Claude Code can use the tools naturally:

- **"Send me a message on Telegram saying the deploy is done"** — uses `send_message`
- **"Check if I sent any instructions"** — uses `get_instructions`
- **"Create a task BUG-42 to fix the login issue"** — uses `create_task`
- **"Mark BUG-42 as completed"** — uses `update_task_status`

You can also send messages from Telegram to Claude Code — they'll be queued and available via `get_instructions`.

## API Endpoints (Webhook Server)

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/webhook` | Telegram bot updates (configured automatically) |
| `POST` | `/webhook/setup` | Register webhook URL with Telegram |
| `GET` | `/webhook/info` | Current webhook status |
| `GET` | `/health` | Health check |

## License

MIT