# telegra-me

MCP server that connects AI agents to your private Telegram bot — send notifications and ask questions while you are away from your computer.

## Website

**Website:** [https://guedes-joaofelipe.github.io/telegra-me/](https://guedes-joaofelipe.github.io/telegra-me/)

Static product landing (`website/`), deployed to GitHub Pages on push to `main`. The site is available after the first successful workflow run and enabling Pages (source: GitHub Actions) in repository settings.

## Problem

Long-running AI agents may need your input while you are away from your desk. telegra-me bridges MCP clients on your computer to Telegram on your phone so agents can notify you and wait for replies.

## Prerequisites

- [uv](https://docs.astral.sh/uv/) — install dependencies with `uv sync` after cloning
- A Telegram bot and chat ID — follow [docs/SETUP.md](docs/SETUP.md)
- Configuration reference: [docs/CONFIG.md](docs/CONFIG.md)

## Quick start

```bash
git clone <repository-url>
cd telegra-me
uv sync
cp config.example.yml config.yml
# Edit config.yml with your Telegram token, chat ID, and API key
make serve
```

The daemon listens on `http://127.0.0.1:8765/mcp` by default.

## Background service

Install a user service that starts at login (no terminal required):

```bash
uv sync
make service-install
```

| Command | Purpose |
|---------|---------|
| `make service-install` | Install and start launchd (macOS) or systemd user service (Linux) |
| `make service-uninstall` | Stop and remove the service |
| `make service-status` | Print whether the daemon is running |

Logs on macOS: `~/Library/Logs/telegra-me/stdout.log` and `stderr.log`.

On Linux, enable lingering if the service must run without an active session:

```bash
loginctl enable-linger "$USER"
```

## MCP clients

telegra-me is **not Cursor-specific**. The daemon speaks standard MCP over HTTP on loopback with Bearer API key auth. Start it first with `make serve` or `make service-install`.

### Cursor

`~/.cursor/mcp.json` or project `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "telegra-me": {
      "url": "http://127.0.0.1:8765/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_API_KEY"
      }
    }
  }
}
```

### Claude Code (CLI)

```bash
claude mcp add --transport http telegra-me http://127.0.0.1:8765/mcp \
  --header "Authorization: Bearer YOUR_MCP_API_KEY"
```

### Claude Desktop

Local Claude Desktop config is stdio-only. Use [`mcp-remote`](https://github.com/geelen/mcp-remote) to bridge stdio → the running HTTP daemon (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "telegra-me": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${MCP_API_KEY_HEADER}"
      ],
      "env": {
        "MCP_API_KEY_HEADER": "Bearer YOUR_MCP_API_KEY"
      }
    }
  }
}
```

Replace `YOUR_MCP_API_KEY` with `server.api_key` from `config.yml` or the `MCP_API_KEY` environment variable.

**Note:** Claude Custom Connectors (cloud-brokered remote MCP) require a public HTTPS URL and do not work with a localhost-only daemon.

## MCP tools

| Tool | Purpose |
|------|---------|
| `send_telegram_message` | One-way text notification |
| `send_telegram_photo` | Send an image (HTTPS URL or local absolute path) |
| `send_telegram_audio` | Send an audio track with optional title/performer |
| `send_telegram_voice` | Send a voice note (OGG/OPUS recommended) |
| `ask_telegram_user` | Ask a question and wait for a reply (text, photo, audio, or voice) |

Media source rules:

- Provide exactly one of `*_url` (HTTPS only) or `*_path` (absolute local file path) per call
- `ask_telegram_user` accepts optional `photo_url` / `photo_path` to attach an image; the question becomes the caption
- Answered `ask_telegram_user` responses include `reply_type` (`text`, `photo`, `audio`, or `voice`); media replies include Telegram `file_id` (bytes are not downloaded back to the agent)

Voice notes work best as OGG files with OPUS encoding (Telegram’s native voice format).

## Troubleshooting

| Symptom | Check |
|---------|-------|
| Daemon exits immediately | `config.yml` missing `telegram.bot_token`, `server.api_key`, or empty `allowed_chat_ids` — see [docs/CONFIG.md](docs/CONFIG.md) |
| MCP client cannot connect | Daemon running? (`make service-status` or `make serve`) |
| HTTP 401 from MCP client | `Authorization: Bearer <api_key>` must match `server.api_key` or `MCP_API_KEY` |
| Telegram messages not received | Bot token valid? `chat_id` in `allowed_chat_ids`? Did you `/start` the bot? |
| `ask_telegram_user` times out | Reply with a text, photo, audio, or voice message from the allowlisted chat while the tool is waiting |
| Media send fails after upgrade | Restart the background service (`make service-uninstall && make service-install`, or `launchctl kickstart -k gui/$UID/com.telegra-me.mcp` on macOS) so launchd loads the new code |
| Linux service stops at logout | Run `loginctl enable-linger "$USER"` |

## Development

```bash
make lint
make tests
make coverage
```

Feature specs: [docs/specs/features/core-platform/](docs/specs/features/core-platform/), [docs/specs/features/media-messaging/](docs/specs/features/media-messaging/).