DEV Community

Cover image for Giving Claude access to your Telegram: the two setups, and why the difference matters
starsearn
starsearn

Posted on • Originally published at starsearn.com

Giving Claude access to your Telegram: the two setups, and why the difference matters

#security #ai #opensource #tutorial

You can give Claude access to your Telegram in about five minutes. Whether that is a good idea depends entirely on which of two very different setups you pick — and most tutorials do not tell you there are two.

I went through the available Telegram MCP servers while writing a setup guide, and the gap between them is much bigger than the feature lists suggest.

The two kinds, and why it matters

MCP — the Model Context Protocol — is the standard that lets AI clients call outside tools. Write one server, and Claude Desktop, Cursor, Windsurf and Codex CLI can all use it. For Telegram, that means an agent can read, search and send messages.

The important question is what the server logs in as.

Bot API servers authenticate with a bot token from @BotFather. A bot can only see chats it was explicitly added to. Your private conversations are invisible to it, and the token is revocable from BotFather in one command.

MTProto servers authenticate with your phone number and store a session file. They log in as you. That means every private DM, every group you lurk in, your saved messages, your contacts — all of it becomes reachable by the agent.

Both are described as "a Telegram MCP server." Only one of them hands over your account.

The setup, for each type

Bot API — no install step, uvx fetches it:

{
  "mcpServers": {
    "telegram-bot": {
      "command": "uvx",
      "args": ["telegram-bot-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "<token from @BotFather>"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Send-only — the narrowest option. The agent can push build alerts and job results to one chat and read nothing at all:

{
  "mcpServers": {
    "telegram-notifier": {
      "command": "npx",
      "args": ["-y", "@harnyk/telegram-notifier-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "<token from @BotFather>",
        "TELEGRAM_CHAT_ID": "<your chat id>"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

MTProto — needs a real install and a one-time interactive login:

uv tool install mcp-telegram
mcp-telegram login
Enter fullscreen mode Exit fullscreen mode 
{
  "mcpServers": {
    "mcp-telegram": {
      "command": "mcp-telegram",
      "args": ["start"],
      "env": {
        "API_ID": "<from my.telegram.org>",
        "API_HASH": "<from my.telegram.org>"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Note the env var names: API_ID and API_HASH, not TELEGRAM_API_ID. I got that wrong on my first pass by assuming, and the server simply refused to start. Read the README rather than pattern-matching from another server's config.

Where the config file lives

This trips people up more than the servers themselves, because every client puts it somewhere different:

Client Path
Claude Desktop ~/Library/Application Support/Claude/claude_desktop_config.json
Cursor ~/.cursor/mcp.json
Windsurf ~/.codeium/windsurf/mcp_config.json
Codex CLI ~/.codex/config.toml

Codex CLI takes TOML, not JSON. Pasting the block above into it will not parse, and the error message does not make the reason obvious. The equivalent is:

[mcp_servers.telegram-bot]
command = "uvx"
args = ["telegram-bot-mcp"]

[mcp_servers.telegram-bot.env]
TELEGRAM_BOT_TOKEN = "<token from @BotFather>"
Enter fullscreen mode Exit fullscreen mode

Also: with Claude Desktop, closing the window is not enough. Quit it properly, or the server will not appear.

The part worth slowing down on

A session file is not a scoped token. It is a live login. Anything that can read it can read your Telegram, and it does not expire the way a rotated password would — revoking means terminating the session from Telegram's device list.

That alone is a reason to keep it out of synced folders and off anything you might git push. But there is a second issue that needs no theft at all.

Your agent reads messages. It also sends them. To an LLM there is no structural difference between "data" and "instruction" — it is all text in the context window. So a message crafted to look like a command is an attack surface, and someone wanting to try it only has to message you.

The blast radius on a bot token is your bot's chats. On a session file, it is your whole account.

None of this makes MTProto servers unusable. It makes them a deliberate choice rather than a default. If you need to search your own history across every chat, that is what it takes. In that case: use a secondary account, keep the session file out of any repo or synced directory, and give the agent read tools before you give it send tools, so a bad prompt cannot message a real person while you are still testing.

Every one of these servers is a community project. Open source, useful, and with no security audit behind them. Read what you are running before you point it at an account that matters.

I wrote the full version up with a config generator — pick your client and access level, and it outputs the exact block plus the right file path for that client, including the TOML variant: Telegram MCP Server: Connect Telegram to Claude, Cursor & AI Agents

If you have shipped something with a Telegram MCP setup, I would genuinely like to hear which type you went with and why — especially if you picked MTProto and have a workflow for keeping it contained.

Top comments (0)