Telegram MCP Server

Give any AI agent access to your Telegram account. An MCP (Model Context Protocol) server that lets Claude Code, Claude Desktop, Cursor, Codex, Windsurf, or any MCP-compatible agent read, search, and send Telegram messages on your behalf.

Built on MTProto via teleproto (the maintained GramJS fork), so it works with your real account — every chat, group, and channel you are in — not just a bot.

Why

Bot API bots only see chats you explicitly add them to. This server signs in as you, so an agent can answer "what did the team decide in the design channel yesterday?", triage your unread DMs, or post a build result to the chat you actually use — without you leaving your editor.

Related MCP server: Telegram MCP Server

Quick start

git clone https://github.com/codedpro/telegram-mcp-server
cd telegram-mcp-server
npm install
cp .env.example .env

1. Get TELEGRAM_API_ID and TELEGRAM_API_HASH from https://my.telegram.org → API development tools, and put them in .env.

2. Log in once and copy the printed session string into .env:

   npm run login

3. Build it:

   npm run build

Connect it to Claude Code

claude mcp add telegram -- node /absolute/path/to/telegram-mcp-server/dist/index.js

Connect it to Claude Desktop / Cursor

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["/absolute/path/to/telegram-mcp-server/dist/index.js"]
    }
  }
}

Tools

Safety

Writes are off by default. telegram_send_message refuses every chat that is not in TELEGRAM_WRITE_ALLOWLIST, so the default install is read-only. Start narrow:

TELEGRAM_WRITE_ALLOWLIST=me,@my_test_group

Two things worth knowing before you run this:

• The session string is your account. Anyone holding it is logged in as you, with no second factor. It is gitignored here — keep it that way, and revoke it from Telegram → Settings → Devices if it ever leaks.

• Automating a personal account is against Telegram's ToS if you spam with it. Personal, low-volume, human-paced use is what userbots have always been used for and is broadly fine; blasting messages will get the account limited or banned. If you only need a bot identity, use the Bot API instead — it is the supported path.

Roadmap

• Read/unread state and mark-as-read

• Media: download and send files, photos, voice notes

• Streaming: push new messages to the agent as they arrive

• npx telegram-mcp-server with zero-config setup

• Optional Bot API mode for people who do not want a userbot

License

MIT