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/

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 — install dependencies with uv sync after cloning
• A Telegram bot and chat ID — follow docs/SETUP.md
• Configuration reference: docs/CONFIG.md

Quick start

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):

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:

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:

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

Claude Code (CLI)

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 to bridge stdio → the running HTTP daemon (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "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
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

make lint
make tests
make coverage

Feature specs: docs/specs/features/core-platform/, docs/specs/features/media-messaging/.