claude-ops-telegram-server — Claude Code MCP server
Connects a personal Telegram account to your coding agent via MTProto. Lets assistants read private direct messages, search conversation history, and send replies.
claude mcp add claude-ops-telegram-server -e TELEGRAM_API_ID=<TELEGRAM_API_ID> -e TELEGRAM_API_HASH=<TELEGRAM_API_HASH> -e TELEGRAM_PHONE=<TELEGRAM_PHONE> -e TELEGRAM_SESSION=<TELEGRAM_SESSION> -- npx -y claude-ops-telegram-serverWhat claude-ops-telegram-server does
The server relies on gram.js and user-level MTProto authentication instead of BotFather bots. Bots cannot inspect private direct messages between two people. By authenticating as a user, the assistant gains access to personal DMs, groups, and channels. It provides four tools: list_dialogs, get_messages, send_message, and search_messages.
Setting this up requires an api_id and api_hash from https://my.telegram.org/apps. You must run an initial interactive authentication step to verify SMS codes and 2FA, which generates the TELEGRAM_SESSION string.
Treat TELEGRAM_SESSION like a raw password and keep it out of version control. If you trigger Telegram account limits during frequent queries, expect a temporary cooldown lasting 15 to 30 minutes.
What it helps with
- inspect private Telegram direct messages inside development workflows
- run full-text message search across all active chats
- review recent conversations alongside unread counters
- post replies or channel updates directly from a personal profile
Example prompts for the agent
- Check recent unread direct messages using list_dialogs.
- Search for messages mentioning 'deployment issue' across all Telegram chats.
- Send a confirmation message to a contact using send_message.
How to install claude-ops-telegram-server
Platform CLI
claude mcp add claude-ops-telegram-server -e TELEGRAM_API_ID=<TELEGRAM_API_ID> -e TELEGRAM_API_HASH=<TELEGRAM_API_HASH> -e TELEGRAM_PHONE=<TELEGRAM_PHONE> -e TELEGRAM_SESSION=<TELEGRAM_SESSION> -- npx -y claude-ops-telegram-serverReplace <…> with your own values
Platform CLI
codex mcp add telegram-server --env TELEGRAM_API_ID=<TELEGRAM_API_ID> --env TELEGRAM_API_HASH=<TELEGRAM_API_HASH> --env TELEGRAM_PHONE=<TELEGRAM_PHONE> --env TELEGRAM_SESSION=<TELEGRAM_SESSION> -- npx -y claude-ops-telegram-serverReplace <…> with your own values
Config file
{
"mcpServers": {
"telegram-server": {
"command": "npx",
"args": [
"-y",
"claude-ops-telegram-server"
],
"env": {
"TELEGRAM_API_ID": "<TELEGRAM_API_ID>",
"TELEGRAM_API_HASH": "<TELEGRAM_API_HASH>",
"TELEGRAM_PHONE": "<TELEGRAM_PHONE>",
"TELEGRAM_SESSION": "<TELEGRAM_SESSION>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"telegram-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"claude-ops-telegram-server"
],
"env": {
"TELEGRAM_API_ID": "<TELEGRAM_API_ID>",
"TELEGRAM_API_HASH": "<TELEGRAM_API_HASH>",
"TELEGRAM_PHONE": "<TELEGRAM_PHONE>",
"TELEGRAM_SESSION": "<TELEGRAM_SESSION>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e TELEGRAM_API_ID=<TELEGRAM_API_ID> -e TELEGRAM_API_HASH=<TELEGRAM_API_HASH> -e TELEGRAM_PHONE=<TELEGRAM_PHONE> -e TELEGRAM_SESSION=<TELEGRAM_SESSION> telegram-server npx -y claude-ops-telegram-serverReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about claude-ops-telegram-server
How to install claude-ops-telegram-server in Claude Code?
First obtain your credentials and generate a session token via interactive login. Then add the server by running `claude mcp add claude-ops-telegram-server -e TELEGRAM_API_ID=<TELEGRAM_API_ID> -e TELEGRAM_API_HASH=<TELEGRAM_API_HASH> -e TELEGRAM_PHONE=<TELEGRAM_PHONE> -e TELEGRAM_SESSION=<TELEGRAM_SESSION> -- npx -y claude-ops-telegram-server`.
Why does this server require personal user authentication instead of a bot?
Standard bots cannot access direct messages between human users. MTProto user authentication lets the agent read your personal inbox and reply on your behalf.
How do you handle a session invalidation error?
Re-run node index.js --auth to complete the interactive SMS and 2FA login, then update your environment with the newly generated TELEGRAM_SESSION.
