Codex MCP Telegram

# Codex MCP Telegram An MCP (Model Context Protocol) server that provides a Telegram escalation tool for human-in-the-loop guidance. ## Features - 🔧 **MCP Server**: Exposes Telegram escalation as an MCP tool - 📱 **Telegram Escalation Tool**: MCP tool to ask humans for input over Telegram - 🔒 **Security**: User authentication via allowed user IDs - ⚡ **Async Execution**: Non-blocking command execution - 🧭 **Two-step Flow**: Prompt a human and poll for the answer - 💬 **Agentic Escalation**: Codex explicitly calls an MCP tool to request human guidance ## Prerequisites 1. **Python 3.10+** 2. **Telegram Bot** (for remote access) - Create a bot via [@BotFather](https://t.me/BotFather) on Telegram - Save the bot token ## Installation 1. **Clone or navigate to the project directory** 2. **Install dependencies**: ```bash pip install -r requirements.txt ``` Or install as a package: ```bash pip install -e . ``` ## Configuration The server uses environment variables for configuration: ### Required (for Telegram escalation tool) - `TELEGRAM_BOT_TOKEN`: Your Telegram bot token from BotFather - `TELEGRAM_CHAT_ID`: Chat ID where the escalation prompts should be sent - `TELEGRAM_ALLOWED_USER_IDS`: Comma-separated list of Telegram user IDs allowed to reply ### Example Configuration Create a `.env` file or export environment variables: ```bash export TELEGRAM_BOT_TOKEN="your_bot_token_here" export TELEGRAM_CHAT_ID="123456789" export TELEGRAM_ALLOWED_USER_IDS="123456789,987654321" ``` ## Usage ### As MCP Server (stdio) Run the server: ```bash python -m codex_mcp_server.server ``` Or use the installed script: ```bash codex-mcp-telegram # or (backward compatibility alias) codex-mcp-server ``` The server communicates via stdio following the MCP protocol. ### Telegram MCP Escalation Tools The MCP tool `telegram_prompt` sends a message to the configured chat and returns a `correlation_id`. Use `telegram_poll` to check for a reply using that ID. **Reply format:** `#<correlation_id> <answer>` Example message: ``` ❓ MCP Escalation Should we proceed with the migration? Reply with #<id> <answer> ``` ### Getting Your Telegram User ID 1. Start a chat with your bot 2. Send `/start` 3. The bot will show your User ID if you're not authorized 4. Add this ID to `TELEGRAM_ALLOWED_USER_IDS` or use `TELEGRAM_CHAT_ID` ## MCP Tools The server exposes the following MCP tools: ### `telegram_prompt` Send a Telegram message and return a correlation ID. **Parameters:** - `question` (required): Question to send - `context` (optional): Additional context to include **Response:** Returns JSON with `correlation_id`. ### `telegram_poll` Check for a human response associated with a correlation ID. **Parameters:** - `correlation_id` (required): ID returned from `telegram_prompt` **Response:** Returns JSON with: - `status`: `pending`, `answered`, `expired`, or `unknown` - `answer`: Present when `status` is `answered` ## Security Considerations 1. **Authentication**: Always configure `TELEGRAM_ALLOWED_USER_IDS` to prevent unauthorized access. 2. **Command Injection**: The server validates command length and uses proper subprocess execution. However, be cautious with prompts that may contain sensitive information. 3. **Network**: The Telegram bot requires network access. Ensure your firewall allows outbound connections to `api.telegram.org`. 4. **Tokens**: Never commit your bot token to version control. Use environment variables or secure configuration files. ## Troubleshooting ### "Telegram bot not starting" - Check that `TELEGRAM_BOT_TOKEN` is set correctly - Verify network connectivity to Telegram API - Check logs for detailed error messages ### "Unauthorized" errors - Verify your User ID is in `TELEGRAM_ALLOWED_USER_IDS` or `TELEGRAM_CHAT_ID` matches ### Telegram polling and timeouts - Ensure `TELEGRAM_CHAT_ID` matches the chat where the bot should post escalation messages - Replies must include the correlation ID: `#<id> <answer>` - If timeouts persist, confirm the bot has permission to read messages in the chat ## MCP Client Configuration (Codex CLI) Add the MCP server in your Codex CLI configuration so it can call `telegram_prompt` and `telegram_poll`: ```json { "mcpServers": { "codex-mcp-telegram": { "command": "codex-mcp-telegram", "args": [] } } } ``` ## Development ```bash # Install in development mode pip install -e . # Run tests (if available) pytest # Run with debug logging PYTHONPATH=. python -m codex_mcp_server.server ``` ## Manual Verification Checklist If automated tests are not available, verify the following manually: - Start the MCP server. - Call `telegram_prompt` and confirm the Telegram message includes the correlation ID and reply instructions. - Reply with `#<id> <answer>` from an allowed user ID. - Call `telegram_poll` and confirm the tool returns `status=answered` and the answer. - Reply without `#<id>` and confirm nothing happens. - Reply from an unallowed user ID and confirm nothing happens. - Wait for the request to expire and confirm the tool returns `status=expired`. ## License MIT License ## Contributing Contributions welcome! Please ensure code follows PEP 8 style guidelines and includes appropriate error handling.