Codex MCP Telegram Server

Provides Telegram-based escalation tools for MCP with authenticated human feedback via chat and poll-based replies.

python

GitHub Stars

python

Language

6 months ago

First Indexed

3 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "rahul23aug-codex-mcp-telegram": {
      "command": "python",
      "args": [
        "-m",
        "codex_mcp_server.server"
      ],
      "env": {
        "TELEGRAM_CHAT_ID": "YOUR_CHAT_ID",
        "TELEGRAM_BOT_TOKEN": "YOUR_BOT_TOKEN",
        "TELEGRAM_ALLOWED_USER_IDS": "ID1,ID2"
      }
    }
  }
}

You run a Codex MCP Server that provides a Telegram escalation tool. It lets you prompt a human for input via Telegram and poll for the answer, all within the MCP framework. This is useful when you want quick, asynchronous human-in-the-loop guidance during automated workflows while keeping control over who can respond and when.

How to use

You interact with the Telegram escalation tools from your MCP client. Start the MCP server locally, then call the telegram_prompt tool to send a question to Telegram and receive a correlation ID. Use telegram_poll with that correlation ID to retrieve the human's answer once it’s provided. The system enforces a two-step flow: first prompt a human, then poll for the response.

Typical usage pattern: you issue a prompt containing your question and optional context, receive a correlation ID, wait for a human to reply in Telegram, and then poll to get the answer. Replies must follow the format #<correlation_id> <answer> to be recognized. Only authorized Telegram user IDs can respond.

How to install

Prerequisites: you need Python 3.10 or newer.

Ensure you have Python and pip installed on your system.
Install dependencies or install in editable mode.
Run the MCP server locally to start handling telegram prompts and polls.

Configuration and security

Configure your Telegram bot and access control by setting environment variables. The required variables for the Telegram escalation tool are TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID, and TELEGRAM_ALLOWED_USER_IDS. TELEGRAM_ALLOWED_USER_IDS is a comma-separated list of user IDs allowed to reply. Use a .env file or export the variables in your shell before starting the server.

export TELEGRAM_BOT_TOKEN="your_bot_token_here"
export TELEGRAM_CHAT_ID="123456789"
export TELEGRAM_ALLOWED_USER_IDS="123456789,987654321"

Troubleshooting

If the Telegram bot does not start, verify that TELEGRAM_BOT_TOKEN is set correctly and that the server can reach the Telegram API. Check logs for error messages. If you encounter unauthorized errors, confirm your user ID is included in TELEGRAM_ALLOWED_USER_IDS and that the chat ID matches the intended Telegram chat.

For polling issues, ensure the reply includes the proper format #<correlation_id> <answer> and that you are polling with the correct correlation_id returned by telegram_prompt.

Development

To run in development mode, start the server using the standard Python invocation.

python -m codex_mcp_server.server

Available tools

telegram_prompt

Send a Telegram message with a question and return a correlation_id for tracking the escalation.

telegram_poll

Check for a human response associated with the given correlation_id and report the status and answer when available.

Built by

VeilStrat

AI signals for GTM teams