lingtai-telegram 0.1.0

LingTai Telegram MCP server — bot API client with LICC inbox callback.

lingtai-telegram

LingTai Telegram MCP server — Bot API client with multi-account support and LICC inbox callback.

This is the canonical setup, configuration, and troubleshooting doc for the lingtai-telegram MCP. It is fetched by LingTai agents (or anyone else) when they need to install or configure this server.

MCP / LICC contract spec: see the lingtai-anatomy skill, reference/mcp-protocol.md, for the canonical specification of the catalog → registry → activation chain, environment-variable injection, and the LICC v1 inbox callback protocol. The reference client implementation is src/lingtai_telegram/licc.py in this repo (vendored verbatim into all first-party LingTai MCP repos — copy it if you're writing your own).

Tools

One omnibus MCP tool: telegram(action=...). Actions: send, check, read, reply, search, delete, edit, contacts, add_contact, remove_contact, accounts. Compound message IDs: account_alias:chat_id:message_id.

Inbound messages (LICC)

Inbound Telegram updates flow into the host agent's inbox via the LingTai Inbox Callback Contract. Each new message is delivered as a LICC event with:

• from — username (or first_name as fallback).
• subject — "telegram message from <user> via <account_alias>".
• body — a ~300 char preview of the message text (use telegram(action="check"|"read") to see the full conversation).
• metadata.message_id — compound ID for reply/delete/edit.
• metadata.account — which configured bot received it.
• metadata.chat_id, metadata.has_media, metadata.has_callback — routing flags.

Install

# Into the LingTai agent's venv (typically ~/.lingtai-tui/runtime/venv/)
pip install git+https://github.com/Lingtai-AI/lingtai-telegram.git

After install, python -m lingtai_telegram (or the lingtai-telegram script) starts the MCP server over stdio.

Configure

The server reads its bot config from a JSON file pointed at by LINGTAI_TELEGRAM_CONFIG. Recommended path: .secrets/telegram.json inside the agent's working directory. Plaintext only — this MCP does not support *_env indirection.

Config schema

{
  "accounts": [
    {
      "alias": "myagent",
      "bot_token": "1234567890:ABCdefGhIJklMNOpqRSTuvwxyz",
      "allowed_users": [123456789, 987654321],
      "poll_interval": 1.0
    }
  ]
}

• alias — human-friendly name for this account; used as the account parameter in tool calls.
• bot_token — issued by @BotFather. Format: <bot_id>:<auth_string>.
• allowed_users — optional allow-list of Telegram user IDs (integers). When set, updates from other users are silently ignored. Omit to accept any sender.
• poll_interval — seconds between getUpdates long-polls (default 1.0).

Activation in LingTai

{
  "addons": ["telegram"],
  "mcp": {
    "telegram": {
      "type": "stdio",
      "command": "/path/to/your/python",
      "args": ["-m", "lingtai_telegram"],
      "env": {
        "LINGTAI_TELEGRAM_CONFIG": ".secrets/telegram.json"
      }
    }
  }
}

Then run system(action="refresh") from the agent. The MCP subprocess starts, the per-account poll threads begin, and the omnibus telegram tool becomes available.

Troubleshooting

• LINGTAI_TELEGRAM_CONFIG env var not set — your init.json mcp.telegram.env entry is missing the LINGTAI_TELEGRAM_CONFIG key.
• Telegram config not found — the path resolves but no file exists. Relative paths are resolved against LINGTAI_AGENT_DIR.
• Unauthorized: invalid token specified — wrong or revoked bot token. Re-issue via @BotFather (/mybots → token).
• Server boots but no inbound messages — bot privacy mode may be on. In @BotFather: /setprivacy → Disable (allows the bot to see all messages in groups). Direct messages always work.
• MCP server failed to start — usually the command path in init.json doesn't have lingtai_telegram installed. Confirm with <command> -m lingtai_telegram --help from a shell.
• Tool calls return Telegram manager not initialized — server boot failed (most often a bad token). Check stderr for the underlying exception, fix the config, then system(action="refresh").

License

MIT.