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.

Related MCP server: Telegram Bridge MCP

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

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

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

Development

make lint
make tests
make coverage

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