telegram-call-mcp

telegram-call-mcp

An MCP server that lets AI agents placereal Telegram voice calls and speak a message aloud. The agent calls onetool — make_call — with the text and a repeat count; the server synthesizesspeech (any TTS model on OpenRouter, defaultfish-audio/s1), rings the owner'sTelegram, waits for them to pick up, plays the message, and hangs up.

Built for "wake me up if production is on fire" scenarios: text notificationsare easy to sleep through, a ringing phone is not.

Agent ──make_call("DB is down", repeat=2)──▶ telegram-call-mcp
                                                │  1. TTS via OpenRouter (mp3)
                                                │  2. ffmpeg → WAV 48kHz mono
                                                │  3. Telegram P2P call (py-tgcalls)
                                                ▼
                                        📞 owner's phone rings,
                                           message plays twice

The tool

make_call

Returns a structured result:

{ "status": "answered", "detail": "message played in full", "message_spoken": "DB is down" }

status is one of answered, no_answer, busy, declined, error. Anunanswered call means the message was not delivered — the agent can decideto retry or fall back to texting.

Requirements

• Python 3.10+
• ffmpeg (with ffprobe) in PATH — brew install ffmpeg / apt install ffmpeg
• A dedicated Telegram account for the server (bots can't make calls, soit signs in as a real user account; see Security notes)
• An OpenRouter API key for TTS

Setup

1. Install

pip install telegram-call-mcp        # or: pipx install / uv tool install

Or from source:

git clone https://github.com/maloleg/telegram-call-mcp
cd telegram-call-mcp
pip install .

2. Get Telegram API credentials

1. Sign in at my.telegram.org with the accountthat will be making the calls (a spare/dedicated account, not your own).
2. Open API development tools, create an application (any name, URL can beleft empty).
3. Note the api_id and api_hash.

3. Sign in once

export TELEGRAM_API_ID=123456
export TELEGRAM_API_HASH=abcdef...
export CALL_TARGET_USER_ID=111111111   # your own numeric Telegram user id
export OPENROUTER_API_KEY=sk-or-...

telegram-call-mcp login

The login prompts for the phone number, the code Telegram sends, and the 2FApassword if enabled, then saves a session file to~/.telegram-call-mcp/telegram.session.

Not sure about your numeric user id? Ask@userinfobot on Telegram.

The caller and the callee must be different accounts. Telegram cannotcall itself. Sign the server in with a dedicated account and pointCALL_TARGET_USER_ID at your personal one.

On the receiving account, allow calls from non-contacts (Settings → Privacy →Calls → Everybody) or add the server's account to your contacts — otherwiseTelegram rejects the call before it ever rings.

4. Add to your MCP client

Claude Code:

claude mcp add telegram-call \
  --env TELEGRAM_API_ID=123456 \
  --env TELEGRAM_API_HASH=abcdef... \
  --env CALL_TARGET_USER_ID=111111111 \
  --env OPENROUTER_API_KEY=sk-or-... \
  -- telegram-call-mcp

Claude Desktop / any JSON-config client (claude_desktop_config.json):

{
  "mcpServers": {
    "telegram-call": {
      "command": "telegram-call-mcp",
      "env": {
        "TELEGRAM_API_ID": "123456",
        "TELEGRAM_API_HASH": "abcdef...",
        "CALL_TARGET_USER_ID": "111111111",
        "OPENROUTER_API_KEY": "sk-or-..."
      }
    }
  }
}

That's it. Ask the agent to "call me and say the deploy finished" to test.

Configuration reference

Security notes

• The session file is full access to the Telegram account. It is createdwith your user permissions in ~/.telegram-call-mcp/; treat it like aprivate key. Use a dedicated account so a leak never exposes your personalchats.
• The tool can only call the one user id fixed in the server config — theagent cannot choose an arbitrary callee, dial numbers, or send messages.
• The message text passes through OpenRouter for synthesis; don't have agentsspeak secrets aloud.
• Automating a user account is subject to Telegram's terms; a dedicatedaccount keeps any risk away from your personal one.

Troubleshooting

Development

python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/mypy src
LOG_LEVEL=DEBUG .venv/bin/telegram-call-mcp   # run on stdio

The call machinery lives in caller.py (Telethon + py-tgcalls, pinned to2.3.3 — private-call APIs are version-sensitive), TTS and audio prep intts.py, tool definition in server.py.

License

MIT