Telegram MCP
Enables AI agents to interact with a personal Telegram account via an MTProto user client: reading dialogs and message history, searching messages, sending texts, clicking inline buttons, waiting for replies, checking phone numbers, managing folders and mute settings, and running consent-based campaigns with pacing, caps, stop lists, and an action journal.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Telegram MCP
A local Model Context Protocol server that gives AI agents (Claude Code, Claude Desktop, Codex) access to your own personal Telegram account — reading chats, sending messages, pressing inline buttons, waiting for replies, managing folders and mute, checking phone numbers and running consent-based campaigns.
It is an MTProto user client (built on mtcute), not a
Bot API bot. It runs locally on your computer, talks to Telegram and nothing else, and is
built around one idea: the agent acts with your authority, so the runtime
enforces the boundaries — a pinned account, a stop list, pacing, daily caps,
hard stops on FLOOD_WAIT, and an append-only journal of every action.
Use it only with your own account and only for messages people expect. Unsolicited messages and bulk outreach violate Telegram's terms and get accounts restricted or banned. The session file is a full key to your account — protect it like a password.
Platform support
Platform | Status |
macOS, Apple Silicon | Supported and tested end-to-end on a MacBook Air 13″ (2025, Apple M4, 24 GB), macOS 26.5 |
Windows 10/11, x64 | Supported, not tested on real hardware. Unit tests and the build run in CI on |
Linux | Not packaged: no installer or service unit yet |
Runtime: Bun 1.3.14.
Related MCP server: telegram-mcp-server
Tools
Group | Tools |
Account |
|
Reading |
|
Acting |
|
Phone check |
|
Folders & mute |
|
Campaigns |
|
Deliberately absent (not disabled — not built): delete, leave, block, forward, edit, mark-as-read, deleting or renaming folders, writing contacts, editing the stop list, fetching web pages. A self-test in the binary fails the build if any of them reappears.
Safety model
There are no confirmation dialogs. Your request to the agent is the authorization; the tool call is the act. What the runtime guarantees instead:
Pinned account. The server refuses to start if the session belongs to any user other than
ownerIdinconfig.json.Stop list. Chats in
stopList(plus every recorded opt-out) are refused for actions and silently absent from listings. No tool can extend or shrink it — you edit it by hand.Pacing classes.
soft(bots, existing dialogs, groups) andcold(first message to a stranger) have separate intervals and daily caps; phone checks have their ownlookupbudget. Limits are account-wide, so parallel agents or campaigns never send faster.Hard stops. A
FLOOD_WAITblocks every Telegram RPC until it expires, even across restarts. A send whose outcome is unknown is markedambiguous, is never retried, and stops campaigns until the daemon is restarted.Untrusted text. Everything other people wrote is returned wrapped in
<telegram-message>-style elements, and the server instructs the agent to treat it as data, never as instructions (prompt-injection defence).Frozen campaigns.
campaign_preparefreezes exactrecipient + textpairs and returns a SHA-256;campaign_startrefuses on any mismatch. Groups and channels cannot be campaign recipients.Journal. Every read, send, click and setting change is appended to a local SQLite journal; sends are stored with their exact text, reads without content.
No other egress. Proxy variables are cleared and
PATHis pinned by the launcher; tests fail if any module imports an HTTP or network client.
See docs/design.ru.md (Russian) for the reasoning and docs/authorization.md for the authorization contract.
Architecture
agent session ─┐
agent session ─┼─ launcher.sh (stdio proxy) ──unix socket──► daemon ──MTProto──► Telegram
agent session ─┘ (launchd)One daemon per account, run by launchd (
local.telegram-mcp) on macOS or a per-user scheduled task (TelegramMCP) on Windows. It owns the session file and its singleton lock, the single Telegram connection, the policy layer, pacing and the journal. It starts at login and is restarted if it exits.Every agent session runs a thin stdio proxy (
launcher.shon macOS,telegram-mcp.exe --connecton Windows) into the daemon. The proxy reads no secrets and never opens the session, so any number of sessions can use Telegram at once.On macOS the daemon listens on
session/telegram-mcp.sock, mode0600inside the0700session directory: only your user can connect — the same user that can read the session file anyway. On Windows it is a named pipe\\.\pipe\telegram-mcp-<hash>, and the installation directory is restricted to your user and SYSTEM.The socket is up before Telegram connects, so tools are always listed; while the daemon is connecting or waiting out a
FLOOD_WAIT, a tool call returns the reason and the next retry time.A daemon restart does not drop agent sessions: the proxy reconnects and replays the MCP handshake. A request in flight at that moment gets an explicit "outcome unknown" error and is not retried.
Setup on macOS
1. Get Telegram API credentials
Create an application at https://my.telegram.org → API development tools
and note the api_id and api_hash.
2. Build
git clone https://github.com/architawr/telegram-mcp.git
cd telegram-mcp
scripts/build-release.shThe build requires exactly Bun 1.3.14 and performs a frozen install without
lifecycle scripts, bun audit, typecheck, tests, an offline self-test, an
arm64 build, ad-hoc code signing, and SHA-256 manifests of all inputs and of
the release.
3. Prepare the installation directory
APP="$HOME/Library/Application Support/TelegramMCP"
mkdir -p "$APP/secrets" && chmod 700 "$APP" "$APP/secrets"
printf '%s' 'YOUR_API_ID' > "$APP/secrets/api_id"
printf '%s' 'YOUR_API_HASH' > "$APP/secrets/api_hash"
chmod 600 "$APP/secrets/"*
install -m 600 config.example.json "$APP/config.json"Edit $APP/config.json and set ownerId to your numeric Telegram user ID.
If you don't know it, leave any number — the next step tells you the right one.
4. Sign in once
TELEGRAM_MCP_CONFIG="$APP/config.json" ./dist/telegram-mcp --loginEnter your phone number, the login code and, if enabled, your 2FA password.
This creates the session file. If ownerId does not match the account, the
command prints the right value — put it into config.json. --login never
overwrites an existing session. The MCP server itself never asks for codes or
passwords.
5. Install
./install.sh # every agent host found on this Mac
./install.sh --target=claude-code # Claude Code CLI only (user scope)
./install.sh --target=claude # Claude Desktop only
./install.sh --target=codex # Codex only (project-scoped workspace)The installer verifies checksums and the signature, installs a versioned
release and switches the current symlink atomically, registers the MCP server
with the chosen hosts (backing up their configs first and never writing secrets
into them), installs and starts the launchd daemon, and waits for its socket.
It never creates, copies or replaces the session or the API credentials.
Restart your agent app afterwards (for Claude Desktop: Cmd+Q, then reopen).
6. Verify
launchctl print gui/$(id -u)/local.telegram-mcp | grep -E 'state|pid'
tail "$HOME/Library/Application Support/TelegramMCP/logs/daemon.log"
claude mcp get telegram # Claude CodeThen ask the agent to call telegram_authorization_status: it must report
ownerAuthorized: true and your user ID.
Setup on Windows
Not tested on real hardware yet — see Platform support.
Requires Bun 1.3.14 and PowerShell. Get the API credentials as in step 1 above, then:
git clone https://github.com/architawr/telegram-mcp.git
cd telegram-mcp
bun install --frozen-lockfile --ignore-scripts
bun run build:windows # dist\telegram-mcp.exe
$App = "$env:LOCALAPPDATA\TelegramMCP"
New-Item -ItemType Directory -Force "$App\secrets" | Out-Null
Set-Content -NoNewline "$App\secrets\api_id" 'YOUR_API_ID'
Set-Content -NoNewline "$App\secrets\api_hash" 'YOUR_API_HASH'
Copy-Item config.example.json "$App\config.json" # then set ownerId
.\dist\telegram-mcp.exe --login --config "$App\config.json"
powershell -ExecutionPolicy Bypass -File .\install.ps1 # -Target claude-code | claude | allinstall.ps1 copies the binary to %LOCALAPPDATA%\TelegramMCP\bin, restricts
the directory to your user, registers the scheduled task TelegramMCP
(started at logon, restarted on failure), and registers the server with
Claude Code (claude mcp add --scope user) and/or Claude Desktop
(%APPDATA%\Claude\claude_desktop_config.json). Codex is not wired up on
Windows yet. The daemon log is %LOCALAPPDATA%\TelegramMCP\logs\daemon.log.
Configuration
config.json lives in the installation directory. Relative paths are resolved against
its directory, so the whole installation can be moved to another Mac.
{
"ownerId": "1234567890",
"sessionPath": "./session/session",
"statePath": "./state",
"secrets": { "apiIdFile": "./secrets/api_id", "apiHashFile": "./secrets/api_hash" },
"limits": {
"soft": { "minIntervalMs": 1000, "dailyMax": 1000 },
"cold": { "minIntervalMs": 5000, "dailyMax": 30 },
"lookup": { "minIntervalMs": 5000, "dailyMax": 100 },
"maxCampaignRecipients": 500
},
"stopList": { "chatIds": [], "usernames": [] }
}The file must be a regular file owned by you with no group or other access; unknown keys, malformed values and out-of-range limits are refused.
launcher.shtakes the config only from its own directory and ignores an inheritedTELEGRAM_MCP_CONFIG, so an agent host cannot repoint it.Cold sends spend both the
coldand thesoftdaily cap; phone checks spendlookupandsoft.Switching accounts means a new
config.jsonand a new session — no code changes.
Operating
Task | macOS | Windows |
Restart the daemon (also clears an ambiguous-send stop) |
|
|
Stop it |
|
|
Logs |
|
|
Update |
|
|
Agent sessions reconnect on their own after a restart or an update. To add a
chat to the stop list, edit stopList in config.json and restart the daemon.
The legacy single-process mode (one process per agent session, exclusive lock)
is still available as launcher.sh --stdio.
Uninstall
launchctl bootout gui/$(id -u)/local.telegram-mcp
rm ~/Library/LaunchAgents/local.telegram-mcp.plist
claude mcp remove telegram --scope user # and/or remove it from Claude Desktop / Codex configs
# Delete "$HOME/Library/Application Support/TelegramMCP" only if you no longer
# need the session and the journal.On Windows: Unregister-ScheduledTask -TaskName TelegramMCP, remove the
registration from Claude, then delete %LOCALAPPDATA%\TelegramMCP if you no
longer need it.
Consider also terminating the session in Telegram → Settings → Devices.
Host notes
Claude Code — registered in user scope (
~/.claude.json), so every session in any directory sees it.Claude Desktop —
claude_desktop_config.jsonhas no project scope, so the registration is app-wide. Cloud (Cowork) tasks cannot reach a local stdio server.Codex — the installer removes any global registration and creates a project-scoped config in a dedicated trusted workspace (
TelegramMCP/workspace), with MCP content excluded from Codex memories.The installed workspace contains
AGENTS.mdandCLAUDE.mdwith operating rules for agents; docs/prompt-example.ru.md is an example owner prompt (Russian).
Development
bun install --frozen-lockfile --ignore-scripts
bun run typecheck
bun test
bun run self-testTests never reach Telegram: the client is faked. CI runs them on macOS and
Windows on every push. scripts/live-smoke.ts is a
manual end-to-end check against an installed launcher.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Hosted Telegram MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Multi-tenant Telegram gateway for AI agents — HTTP+stdio, 8 tools, MTProto User API
MCP server for AI agents: posts, messages and comments on WhatsApp, Instagram, TikTok and Facebook.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server that connects AI assistants to your real Telegram account via User API (MTProto). Features default-deny ACL with per-chat permissions, message search, file sending, forwarding, media downloads, and rate limiting.4MIT
- AlicenseNot gradedqualityDmaintenanceA read-only MCP server that lets AI agents read personal Telegram chats from an allowlist of folders, with no send/edit/delete capability.MIT
- AlicenseNot gradedqualityBmaintenanceA safe-by-default MCP server for real Telegram accounts powered by TDLib, enabling AI agents to read and act on your account with read-only mode and human approval for destructive actions.13Apache 2.0
- AlicenseAqualityDmaintenanceAn MCP server that gives AI agents full access to a personal Telegram account via MTProto, enabling chat reading, history search, messaging, media handling, and automations.79MIT