mcp-telegram

AnMCPserver that connects AI assistants like Claude to yourreal Telegram accountvia the User API (MTProto). Not a bot — Claude reads and sends messages as you.

Built withgotd/tdand the officialMCP Go SDK.

Telegram API Terms of Service: This project uses the Telegram User API. You must obtain your ownapi_idandapi_hashfrommy.telegram.organd comply with theTelegram API Terms of Service. Misuse of the User API (spam, bulk messaging, scraping) may result in your account being banned. You are solely responsible for how you use this tool.

- Features
- What you can do with it
- How it compares to chaindead/telegram-mcp
- Quick start
- Client configuration
- Configuration reference
- Security

- Go 1.26+
- A Telegram account
- API credentials frommy.telegram.org(api_idandapi_hash)

npx @prgebish/mcp-telegram serve --config config.yaml

go install github.com/Prgebish/mcp-telegram/cmd/mcp-telegram@latest

git clone https://github.com/Prgebish/mcp-telegram.git cd mcp-telegram go build ./cmd/mcp-telegram

export TG_APP_ID=12345 export TG_API_HASH="your_api_hash" mcp-telegram auth --config config.yaml

$env:TG_APP_ID = "12345" $env:TG_API_HASH = "your_api_hash" mcp-telegram.exe auth --config config.yaml

set TG_APP_ID=12345 set TG_API_HASH=your_api_hash mcp-telegram.exe auth --config config.yaml

telegram: app_id: ${TG_APP_ID} api_hash: ${TG_API_HASH} session_path: ~/.config/mcp-telegram/session.json acl: chats: - match: "@username" permissions: [read, draft, mark_read] - match: "user:123456789" permissions: [read, send] - match: "channel:2225853048" permissions: [read, mark_read] limits: max_messages_per_request: 50 max_dialogs_per_request: 100 rate: requests_per_second: 2.0 burst: 3 logging: level: info

Environment variables in${...}syntax are expanded at load time.

The server communicates over stdio — your MCP client starts and manages the process.

claude mcp add telegram -- /path/to/mcp-telegram serve --config /path/to/config.yaml

Claude Desktop / Claude Code(~/.claude.jsonorclaude_desktop_config.json):

{ "mcpServers": { "telegram": { "command": "/path/to/mcp-telegram", "args": ["serve", "--config", "/path/to/config.yaml"], "env": { "TG_APP_ID": "12345", "TG_API_HASH": "your_api_hash" } } } }

Cursor(Settings > MCP Servers > Add):

{ "telegram": { "command": "/path/to/mcp-telegram", "args": ["serve", "--config", "/path/to/config.yaml"], "env": { "TG_APP_ID": "12345", "TG_API_HASH": "your_api_hash" } } }

The ACL isdefault-deny. Only chats explicitly listed inacl.chatsare accessible, and only with the permissions you specify.

Permission types:read,send,draft,mark_read.

If the same peer matches multiple rules (e.g. via@usernameanduser:ID), permissions are merged — they never shadow each other.

Thelimits.ratesection configures a global token bucket that wraps all Telegram RPC calls:

- requests_per_second— sustained rate (default: 2.0)
- burst— maximum burst size (default: 3)

media: download: [photo, document, video, voice, audio] directory: ~/telegram-media allowed_upload_dirs: - ~/Documents - ~/Downloads

When configured,tg_historywill automatically download media files to the specified directory. Thedownload_toparameter can override the path, but only tomedia.directoryor its subdirectories.

allowed_upload_dirsrestricts which directoriestg_sendcan read files from. File sending is disabled unless this is configured.

- Default-deny ACL— no chat is accessible unless explicitly whitelisted
- Filesystem boundary—tg_sendcan only read files fromallowed_upload_dirs;download_tois restricted to subdirectories ofmedia.directory
- Session file permissions— enforced to0600(owner-only read/write)
- No secret logging— API hashes, session tokens, and auth keys are never written to logs
- No access hash exposure— internal Telegram access hashes are stripped from all tool output
- Rate limiting— prevents accidental API abuse
- Local timezone— date filters use your system timezone, not UTC

If you find this project useful, please give it a star — it helps others discover it.

Encrypted file transfer and communication between AI agents - send and receive files securely with E2E encryption, agent identity, and trust scoring.

Create, edit, and delete email aliases and manage encrypted file shares with anon.li MCP.

Send and receive emails, SMS, and voice calls via Pingram.

Platfone - Receive SMS & Virtual Numbers MCP

Virtual phone number platform for AI agents — rent numbers across 200+ countries, receive SMS, and manage the full activation lifecycle

3 tools for global censorship intelligence (119 countries) + E2E encrypted agent-to-agent messaging with Double Ratchet and post-quantum crypto

Agent-native forum for the x402/A2A ecosystem. The hosted MCP server exposes the whole forum as tools — threads, comments, votes, USDC bounties (Coinbase x402 on Base), provider reviews, and search. Endpoint: https://api.achivx.com/mcp/ (HTTP, OAuth 2.1).

Real SIM-backed mobile numbers for AI agents. Provision phone numbers, receive SMS, and capture OTP codes — bypasses VoIP blocks that reject Twilio/Vonage. 5 tools: provision_number, wait_for_otp, get_messages, release_number, list_numbers.

MCP server for Telegram bots built with aiogram. 30 tools, 7 resources, 3 prompts — messaging, rich media, moderation, interactive keyboards, real-time event streaming, rate limiting, permissions, and audit logging.

Production-grade MCP server for Telegram with dual-mode Bot API + MTProto, 6 composite tools

Local-first MCP server that puts your own LINE and Telegram chats behind one data layer — a daemon on your machine logs in with your own account, stores messages to JSONL + SQLite/FTS5, and exposes them to MCP clients like Claude Code. Not an npx one-liner: you clone the repo and run the daemon yourself.