authStatusLABSCO SUMMARY
It syncs your history to a local database first, so search runs over an archive rather than a live scroll.
Because it uses your personal account over MTProto, it reaches everything you can see — DMs, channels, forum topics — not just what a bot is invited to. The background sync is what makes messagesSearch useful: it is querying a local full-text index of backfilled history, with a source flag to choose archive, live, or both.
What it is
Tgcli — a Telegram CLI with background sync and an optional MCP server, working through your personal account over MTProto rather than the bot API.
What you get
- messagesList and messagesSearch read and full-text-search messages across archive, live, or both, with date and channel filters
- messagesContext pulls the messages around one; messagesGet fetches a single message
- messagesSend and messagesSendFile send text and files, optionally into a forum topic or as a reply
- channelsList, channelsSearch and channelsGet cover your channels; topicsList and topicsSearch handle forum topics
- contactsSearch, groupsList and groupsInfo reach contacts and groups; mediaDownload saves attachments
- Background sync backfills the archive and keeps a local messages.db in step with live
Requirements
Telegram API credentials — an api_id and api_hash created at my.telegram.org/apps — then tgcli auth to log in with your phone number. Install globally with npm and the @kfastov/tgcli package, or via Homebrew. The MCP server is off by default: enable it with tgcli config set mcp.enabled true, and it binds to http://127.0.0.1:8080/mcp.
Setup effort
One command plus credentials — npm install -g @kfastov/tgcli, then supply credentials
USE CASES
01
Finding a message you know you read somewhere
Full-text search across your archived history, narrowed by channel and date.
02
Catching up on one channel
List its recent messages, then pull the context around any that matter.
03
Sending a message or file without opening the app
Send text or attach a file, into a topic or as a reply if you need.
04
Saving an attachment out of a chat
Download the media from a specific message to a path you choose.
05
Finding the right channel or group first
Search your channels or list your groups to get the ID before you act.
42 tools
Listed in project docs. Your client may show a different list.
serverStatussyncJobsListsyncJobsAddsyncJobsRetrysyncJobsCancelsyncRealtimeSetchannelsListchannelsSearchchannelsGetchannelsSetSyncchannelsMetadataGetchannelsMetadataRefreshchannelsTagsSetchannelsTagsListchannelsTagsSearchchannelsTagsAutotopicsListtopicsSearchmessagesListmessagesGetmessagesContextmessagesSearchmessagesSendmessagesSendFilemediaDownloadcontactsSearchcontactsGetcontactsAliasSetcontactsAliasRemovecontactsTagsAddcontactsTagsRemovecontactsNotesSetgroupsListgroupsInfogroupsRenamegroupsMembersAddgroupsMembersRemovegroupsInviteLinkGetgroupsInviteLinkRevokegroupsJoingroupsLeaveBEFORE YOU INSTALL
What to know first
Tools you get
42 tools named in the project's documentation.
Requires
npm on PATH
INSTALLATION
Connect your client
This project publishes no client configuration, so the entry for your client is yours to write.
Server setup
TERMINAL
npm install -g @kfastov/tgcli
