TG multi-account MCP server

by Mesteriis·io.github.Mesteriis/tg-account-mcp·v0.5.2

No reviews yet

Self-hosted, consent-based access to Telegram accounts and bots for MCP clients

A92/100grade A

Write a review Install

What users say

No reviews yet

Be the first

Safety scan

A92/100

full report

Adoption

Growing

0 stars47 downloads/wk

Reviews

Write one

Nobody has reviewed TG multi-account MCP yet.

If you have run it, two minutes of your experience saves the next person an afternoon.

TG multi-account MCP tools (44, 8 write)

write = sends, deletes, buys or posts

Read from the package source without running it. The installed server may list more.

cancel_scheduled_messagewrite action
Cancel one scheduled message by ID.
create_agent_tokenwrite action
Create a scoped bearer token. The plaintext token is returned only once.
create_draftwrite action
Save a private local message draft without contacting Telegram.
delete_draftwrite action
Delete one local draft.
download_attachment
Download one image or file attachment up to 10 MB from a message.
download_attachment_chunk
Read a base64 chunk from an attachment of any size accepted by Telegram.
edit_own_message
Edit a text message previously sent by the selected personal account.
find_chats
Find dialogs by title or contact name across the latest 500 dialogs.
forward_messages
Forward 1–100 existing messages as the selected personal account.
get_capabilities
Describe server features, limits and currently configured identities.
get_chat_history
Read history newest first, optionally inside an inclusive YYYY-MM-DD range.
get_chat_info
Return normalized identity and type metadata for a chat.
get_conversation_snapshot
Get chat metadata, recent history and its latest pinned message.
get_folder_messages
Merge messages from chats in a named folder, newest first, with date filters.
get_inbox_context
Return prioritized unread dialogs with recent message context in one call.
get_message
Get one message by its stable chat and message IDs.
get_message_context
Get a target message with bounded messages immediately before and after it.
get_recent_mentions
List recent messages that mention this account, globally or in one chat.
get_reply_thread
Return a message, its reply ancestry and bounded direct replies.
get_status
Return aggregate readiness counts for configured accounts and bots.
get_unread_inbox
List unread dialogs with mention, reaction and latest-message context.
list_accounts
List stable user account IDs and their readiness state.
list_agent_tokens
List scoped agent tokens without revealing their token material or hash.
list_attachments
List attachment-bearing messages by kind and inclusive calendar range.
list_bots
List stable bot IDs and their readiness state.
list_chats
List chats for one account. Use next_cursor for further pages.
list_drafts
List private local drafts visible to the current agent token.
list_folders
List Telegram chat folders for one account.
list_scheduled_messages
List scheduled messages in one chat.
list_topics
List forum topics for a supergroup.
mark_chat_read
Mark a chat read through an optional message ID.
poll_updates
Poll new, edited, deleted, read and reaction events after a signed cursor.
react_to_message
Set a standard emoji reaction, or remove the account's reaction with null.
resolve_message_link
Resolve a public or private t.me message link to chat, topic and message IDs.
resolve_peer
Resolve a numeric ID, username, t.me link or fuzzy chat title.
revoke_agent_token
Revoke one scoped agent bearer token.
schedule_message
Schedule a plain-text message 10 seconds to 365 days in the future.
search_all_messages
Search every dialog, optionally filtering by date, sender and attachment kind.
search_chat_content
Find links, polls, GIFs, video notes, voice notes or pinned messages.
search_messages
Search within one chat for one account; the cursor is bound to both.
send_as_botwrite action
Send plain text as the selected bot. Never falls back to a user or another bot.
send_as_userwrite action
Send plain text as the selected personal account. Never falls back to another ID.
send_attachmentwrite action
Send an existing Telegram attachment as the selected personal account.
send_draftwrite action
Send one pending draft; subsequent calls return its stored send receipt.

Public scan report

scanner v0.1.10 · 2026-10-15 · same rubric, same numbers if you re-run it

no findings

Code scan26 source files scanned25/25
–Live reliabilityno gateway calls yet and no remote to proben/a
–Tool poisoningtools not inspected (local package is not executed); not countedn/a
Auth qualitylocal package, no credentials required12/15
Maintenancelast push 1 days ago15/15
Maintainer identityregistry namespace matches repository owner; GitHub account older than a year8/10

Overall 92/100. Components that don't apply are left out of the denominator. Any critical finding is an F.Rubric Appeal a finding JSON

How TG multi-account MCP compares

Against every graded MCP server, from our own scans and uptime checks. Updated after each scan run.

Safety score: 92/100; higher than 95% of 48,255 servers
Tools: 44; the typical server has 7
Tools that change things: 18%; typical: 0%. Fewer write tools means less an agent can break
Downloads a week: 47; more than 39% of 12,191 servers with a package

What its tools let an agent do: 33 read · 2 create · 2 change · 3 delete · 4 send or post

Install TG multi-account MCP in Claude Code, Cursor or VS Code

claude mcp add tg-account-mcp -- uvx tg-account-mcp

Add to Cursor

What the publisher says

From the TG multi-account MCP repository's README, as published. We do not edit it. Read it on GitHub

TG multi-account MCP

Русская документация

A self-hosted Model Context Protocol server that lets AI agents work with Telegram through explicitly selected user accounts and optional bots. Accounts are connected in a local web wizard by scanning a QR code and entering a Telegram 2FA password when required.

The server is designed as an agent tool rather than a Telegram client. It can search chat history, read folders and threads, download attachments, track updates, create drafts, and send messages. Every operation names the account or bot it uses; the server never silently selects a sender.

[!IMPORTANT]

A Telegram session can access the corresponding account. Run this service on infrastructure

you control, protect the state directory and MCP tokens, and give agent tokens only the

permissions they need.

This is an unofficial integration that uses the Telegram API and is not affiliated with or endorsed by Telegram.

What it supports

or tokens.

Multiple Telegram user accounts, each with its own QR/2FA onboarding flow and session.
Optional Telegram bots connected independently through BotFather tokens.
Streamable HTTP MCP with Bearer-token authentication.
Chat, folder, message, attachment, mention, topic, reply-thread, and global search tools.
Cyrillic/Latin transliteration matching when finding chats.
User and bot sending, edits, scheduling, forwarding, reactions, drafts, and idempotency keys.
Scoped agent tokens with read, send, and admin permissions plus identity/chat allowlists.
A private operations dashboard that records metadata without message text, queries, passwords,

Docker Compose deployment with Caddy-managed HTTPS.

The current release exposes 44 MCP tools. See the tool catalog for the full list and behavior notes.

Requirements

my.telegram.org

Python 3.12+
uv
A Telegram apiid and apihash from

Docker and a domain are required only for the Compose deployment.

Quick start

uv sync --frozen
uv run tg-mcp setup
TG_MCP_PORT=8765 uv run tg-mcp serve

setup requests the Telegram API credentials through local terminal input and generates a random MCP access token. It does not request your phone number or account password.

Open http://127.0.0.1:8765/ and follow the account wizard:

Scan the QR code in Telegram → Settings → Devices → Link Desktop Device.
Enter the Telegram cloud password if 2FA is enabled.
Give the account a local display name.

Repeat the wizard to add more accounts. Bots are optional and are added separately in the dashboard. Their tokens are verified with Telegram before storage.

The state directory defaults to ~/.local/share/tg-mcp. Override it with --state-dir or TGMCPSTATE_DIR.

Connect an MCP client

Print the main token locally:

uv run tg-mcp show-token

Configure the client to use the Streamable HTTP endpoint and Bearer header:

{
  "url": "http://127.0.0.1:8765/mcp",
  "headers": {
    "Authorization": "Bearer <MCP_TOKEN>"
  }
}

The surrounding configuration shape depends on the MCP client. Clients that require OAuth and cannot set a Bearer header are not currently supported.

Start with getcapabilities, listaccounts, and listbots. All account and bot operations require an explicit stable ID such as acct… or bot_….

For a folder-oriented request such as “show today’s messages in ITQ that concern my tasks,” an agent can call listfolders, then getfoldermessages with matching datefrom and date_to values and an IANA timezone such as Europe/Madrid, provided that processing this content is permitted under the consent requirements below.

Codex plugin

Shortened. The full README is on GitHub.

Nothing above is checked by us. What we check is on the safety report.

TG multi-account MCP: common questions

Is TG multi-account MCP server safe?: Yes, by our scan: it is graded A (92/100). Read the TG multi-account MCP safety report
How do I install TG multi-account MCP?: It runs on your machine. Copy the Claude Code, Cursor, VS Code or Claude Desktop config from the install section.
Does TG multi-account MCP need an API key?: No secret keys are declared. It reads 1 setting from the environment.
Is TG multi-account MCP maintained?: The last commit was 21 days ago (2026-10-14). The latest release is v0.5.2.
How does TG multi-account MCP compare with other MCP servers?: safety score 92/100 (higher than 95% of 48,255 servers); tools 44 (the typical server has 7); tools that change things 18% (typical: 0%. Fewer write tools means less an agent can break). Full comparison.