q0t-telegram-mcp

A production-quality Telegram MCP server in Python that actually sends messages.

Why This Exists

The reference Go implementation (@chaindead/telegram-mcp) ships with two bugs that make it silently broken:

1. `tg_send` saves a draft instead of sending. The implementation calls MessagesSaveDraft instead of SendMessage. Messages are stored as unsent drafts — they never arrive at the recipient.
2. Parameter naming inconsistency. The MCP tool advertises a parameter named to, but the Go struct uses the JSON tag name. The value passed by the caller is silently ignored and the dialog name is never set.

This project fixes both and builds a reliable, well-tested replacement.

MCP Tools

Identifying a dialog

Three selectors are available for tg_dialog, tg_send, and tg_read. Supply at least one:

When more than one selector is supplied, priority is: dialog_id > username > name.

Disambiguation: when to use dialog_id vs name

Use name only as a fallback. Two real problems arise when you rely on it:

1. Duplicate names. If two contacts are both named "Adilet", name-based resolution scans your dialog list and picks whichever comes first — it may be the wrong person.
2. Display names are not Telegram handles. Telethon's get_entity() cannot resolve a human display name like "Алёна 😍" directly. Under the hood this server scans your cached dialog list for an exact match, which is slower and can fail if the dialog is not yet cached.

Recommended workflow:

1. Call tg_dialogs to get the list. Each entry includes both id and username (when the contact has a public handle).
2. Pass dialog_id (preferred) or username to tg_send, tg_dialog, and tg_read.
3. Fall back to name only when neither id nor username is available (e.g. phone-only contacts without a handle).

Prerequisites

Obtain API credentials from https://my.telegram.org/apps:

Installation & Authentication

No repository clone is needed. Use uvx to run directly from PyPI.

API credentials (TG_APP_ID and TG_API_HASH) can be supplied either as environment variables or as CLI flags — flags take priority.

First-time authentication

# Via environment variables
TG_APP_ID=your_app_id TG_API_HASH=your_api_hash uvx q0t-telegram-mcp auth --phone +1234567890

# Via CLI flags (no env vars needed)
uvx q0t-telegram-mcp auth --phone +1234567890 --app-id your_app_id --api-hash your_api_hash

With 2FA enabled

# Via environment variables
TG_APP_ID=your_app_id TG_API_HASH=your_api_hash uvx q0t-telegram-mcp auth --phone +1234567890 --password your_2fa_password

# Via CLI flags
uvx q0t-telegram-mcp auth --phone +1234567890 --app-id your_app_id --api-hash your_api_hash --password your_2fa_password

You will be prompted to enter the OTP sent to your Telegram app (or SMS). After successful authentication, a session file is saved locally and subsequent connections reuse it automatically.

Session File Location

The session is stored at .telegram-mcp/session.session relative to whichever directory auth was run from. The MCP server must be started from the same directory so it can find the session.

For Claude Code users, add .telegram-mcp/ to .gitignore to avoid committing credentials:

.telegram-mcp/

Claude Code Configuration

Add the following to your project's .mcp.json:

{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": ["q0t-telegram-mcp"],
      "env": {
        "TG_APP_ID": "your_app_id",
        "TG_API_HASH": "your_api_hash"
      }
    }
  }
}

Claude Code starts the server from your project root, so run auth from the same directory before using the tools.

Publishing to PyPI (Maintainers)

uv build
uv publish