Telegram MCP
MCP server: Telegram MCP
Installation
npx telegram-mcpAsk AI about Telegram MCP
Powered by Claude Β· Grounded in docs
I know everything about Telegram MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation

What is this?
telegram-mcp is an MCP server that exposes your Telegram account as tools for AI agents. It uses MTProto (userbot protocol) β not Bot API β which means it can access any chat, channel, or DM your account has access to, without needing to add a bot.
Connect it to Claude, Codex, or any MCP-compatible client and let agents read messages, search dialogs, download media, and fetch message links β all from your personal Telegram.
Use Cases
π° Channel digest Ask your agent to pull the last 50 unread messages from your favorite tech channels, filter for substance, and summarize what's worth reading.
"Fetch unread messages from @some_channel since yesterday and summarize the key points"
π Search your history Find that message with the link someone sent you three weeks ago in a group of 500 people.
"Search my dialogs for 'MCP server' and find where I discussed it"
π€ Agent inbox monitoring Wire your AI agent to periodically check specific channels and pipe interesting content into your workflow β notes, capture files, summaries.
π Media extraction Download files, images, or documents from any message your agent finds β useful for automating research pipelines.
Tools
| Tool | Description |
|---|---|
search_dialogs | Search chats, groups, and channels by name or username |
get_messages | Fetch messages with date range, unread filter, and mark-as-read support |
search_messages | Full-text search across all chats or within a specific chat |
media_download | Download media (photo, video, document) from a message to a local file |
message_from_link | Fetch a message by its t.me/... link |
delete_messages | Delete messages from a chat (requires opt-in via bot-data/config.yml) |
send_message | Send a text message to a chat (requires opt-in via bot-data/config.yml) |
send_file | Send a local file to a chat as a document (requires opt-in via bot-data/config.yml) |
Full reference with parameters and examples β docs/tools.md
Quick Start
1. Get Telegram API credentials
Go to my.telegram.org, create an app, and grab your API_ID and API_HASH.
2. Install
git clone https://github.com/newink/telegram-mcp.git
cd telegram-mcp
bun install
cp .env.example .env
# Fill in TELEGRAM_API_ID and TELEGRAM_API_HASH
3. Start and authorize via browser
bun start
If no session is configured, the server starts in setup mode and prints an auth URL:
WARN: auth required β open URL to connect Telegram account
url: "http://localhost:3000/auth?token=a3f9b2c1-..."
Open the URL in your browser β you'll see an auth page where you can sign in with a QR code (scan with Telegram β Settings β Devices β Link Desktop Device) or your phone number. After signing in, the session is saved to .env and the server is ready.
One-time token β the
/authURL is only valid once per server start and expires after successful login. Restarting the server generates a new token.
That's it. Point your MCP client at http://localhost:3000/mcp.
Prefer the terminal? Use bun run auth
bun run auth
# Interactive CLI: QR code or phone number, saves session to .env
bun start
Both flows produce the same result β pick whichever fits your setup.
Docker
Run with Docker Compose β no Bun installation needed:
cp .env.example .env
# Fill in TELEGRAM_API_ID and TELEGRAM_API_HASH
docker compose up
The first time you start the container without a TELEGRAM_SESSION, it will print an auth URL β open it in your browser to sign in. The session is persisted to ./bot-data/ so you only need to auth once.
Manual docker run
docker build -t telegram-mcp .
docker run -p 3000:3000 \
--env-file .env \
-e ENV_FILE=/app/bot-data/.env \
-v ./bot-data:/app/bot-data \
telegram-mcp
Pull pre-built image
# Latest stable
docker pull newink/telegram-mcp
# Or from GitHub Container Registry
docker pull ghcr.io/newink/telegram-mcp
Supported platforms: linux/amd64, linux/arm64 (Raspberry Pi, Apple Silicon via Rosetta).
Connect to Your AI Client
Claude Desktop
Start the server first (bun start), then add to claude_desktop_config.json:
{
"mcpServers": {
"telegram": {
"type": "http",
"url": "http://localhost:3000/mcp"
}
}
}
mcporter / OpenClaw
{
"mcpServers": {
"telegram": {
"baseUrl": "http://localhost:3000/mcp"
}
}
}
Direct HTTP (any client)
# Initialize session first, then call tools:
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_dialogs","arguments":{"query":"news"}}}'
Environment Variables
| Variable | Required | Description |
|---|---|---|
TELEGRAM_API_ID | Yes* | From my.telegram.org |
TELEGRAM_API_HASH | Yes* | From my.telegram.org |
TELEGRAM_SESSION | Yes* | Generated by browser auth or bun run auth |
PORT | No | Server port (default: 3000) |
LOG_LEVEL | No | Pino log level: trace|debug|info|warn|error (default: info) |
TELEGRAM_MOCK | No | Set true to use mock data (no real Telegram needed) |
*Not required when TELEGRAM_MOCK=true.
Development
bun dev # Start with hot reload
bun test # Run tests (uses mock automatically)
bun run typecheck # TypeScript check
bun run lint # Biome lint + format
bun run lint:fix # Auto-fix lint issues
bun run knip # Find dead code
bun run audit # Full health check (types + lint + structure + TODOs)
Mock mode β develop and test without a real Telegram account:
TELEGRAM_MOCK=true bun dev # server with fake data
TELEGRAM_MOCK=true bun test # run tests
Mock data includes sample dialogs, messages, and media β enough to build and test new tools without touching the real API.
Project structure and architecture β docs/architecture.md MTProto specifics and gotchas β docs/mtproto.md Adding new tools β docs/tools.md
Built With
- Bun β runtime & package manager
- mtcute β MTProto client for TypeScript
- @modelcontextprotocol/sdk β MCP server SDK
- Zod β schema validation
- Biome β linter & formatter
License
MIT
