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
-
Python 3.10+
-
Telegram Bot (for remote access)
- Create a bot via @BotFather on Telegram
- Save the bot token
Installation
-
Clone or navigate to the project directory
-
Install dependencies:
pip install -r requirements.txtOr install as a package:
pip install -e .
Configuration
The server uses environment variables for configuration:
Required (for Telegram escalation tool)
TELEGRAM_BOT_TOKEN: Your Telegram bot token from BotFatherTELEGRAM_CHAT_ID: Chat ID where the escalation prompts should be sentTELEGRAM_ALLOWED_USER_IDS: Comma-separated list of Telegram user IDs allowed to reply
Example Configuration
Create a .env file or export environment variables:
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:
python -m codex_mcp_server.server
Or use the installed script:
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
- Start a chat with your bot
- Send
/start - The bot will show your User ID if you're not authorized
- Add this ID to
TELEGRAM_ALLOWED_USER_IDSor useTELEGRAM_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 sendcontext(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 fromtelegram_prompt
Response: Returns JSON with:
status:pending,answered,expired, orunknownanswer: Present whenstatusisanswered
Security Considerations
-
Authentication: Always configure
TELEGRAM_ALLOWED_USER_IDSto prevent unauthorized access. -
Command Injection: The server validates command length and uses proper subprocess execution. However, be cautious with prompts that may contain sensitive information.
-
Network: The Telegram bot requires network access. Ensure your firewall allows outbound connections to
api.telegram.org. -
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_TOKENis 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_IDSorTELEGRAM_CHAT_IDmatches
Telegram polling and timeouts
- Ensure
TELEGRAM_CHAT_IDmatches 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:
{
"mcpServers": {
"codex-mcp-telegram": {
"command": "codex-mcp-telegram",
"args": []
}
}
}
Or add it via the Codex CLI:
codex mcp add telegram -- python -m codex_mcp_server.server
Added global MCP server 'telegram'.
codex mcp list
Development
# 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_promptand confirm the Telegram message includes the correlation ID and reply instructions. - Reply with
#<id> <answer>from an allowed user ID. - Call
telegram_polland confirm the tool returnsstatus=answeredand 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.