tgcli MCP server

Commit Nov 12, 2026

kfastov/tgcli · javascript · MIT

Lets an AI client search, archive, and send Telegram messages on a personal account via MTProto.

Also known as kfastov/tgcli

Communication Productivity & Office Filesystem & OS

GitHub ↗

Stars: 45
Tools: —
Downloads, 30 days: —
Latest version: —
Last commit: Nov 12, 2026
License: MIT

What is tgcli MCP?

tgcli lets an AI client search, archive, and send Telegram messages on a personal account via MTProto.

Summary generated from the project's README

About tgcli MCP server

Managing personal Telegram communications through an AI client is possible with tgcli. This tool allows users to search, archive, and send messages using the MTProto protocol rather than the standard bot API. It operates locally on your machine and requires your own Telegram api_id and api_hash obtained from the Telegram developer portal to authenticate your personal account.

Developers can enable the MCP functionality through the configuration settings to connect it to their preferred AI client. Once active, the server runs on a local host and port of your choosing, such as 127.0.0.1:8080. The system manages data through a local store containing a messages database and session files. It supports various specific tasks including managing group topics, downloading media, searching through archived messages, and handling channel tags or metadata.

Users interact with the system via the tgcli command line to start the server or manage background sync services. The tool provides specialized commands for contacts, groups, and channel metadata to ensure the AI has a comprehensive view of your Telegram environment.

What you can do with it

1Search archived messagesAsk the AI to find a specific piece of information within your archived Telegram history.
2Send Telegram messagesInstruct your AI client to send a text message or a file to a specific contact or username.
3Download media filesHave the AI retrieve and download media content from your Telegram chats.
4Manage forum topicsUse the AI to navigate or interact with specific topics within Telegram forums.

Written from the project's README. Every use case is checked against a quote from it.

Automated checks

Ran Nov 14, 2026Full report →

100/100

Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work

Show this score in your README

Source repository linked and reachablekfastov/tgcli is public and reachablegithub.com/kfastov/tgcli ↗Pass
Package names this repository as its sourceNot checked
Build provenance (Sigstore attestation)Not checked
Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
Commit or release in the last yearLast commit or release 2026-11-12github.com/kfastov/tgcli ↗Pass
OpenSSF ScorecardNot checked
Package name not close to a popular packageNot checked
No critical advisory in the package or its dependenciesNot checked
No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
Destructive tools are labelledNot checked
Remote endpoint answers the MCP handshakeNot checked

README

View on GitHub

tgcli

Telegram CLI with background sync and an optional MCP server for your personal account (MTProto, not bot API).

Installation

npm install -g @kfastov/tgcli

brew install kfastov/tap/tgcli

Authentication

Get Telegram API credentials:

Go to https://my.telegram.org/apps
Log in with your phone number
Create a new application
Copy api_id and api_hash

Then authenticate:

tgcli auth

Quick start

tgcli auth
tgcli sync --follow
tgcli messages list --chat @username --limit 20
tgcli messages search "course" --chat @channel --source archive
tgcli send text --to @username --message "hello"
tgcli server

Commands

tgcli auth           Authentication and session setup
tgcli config         View and edit config
tgcli sync           Archive backfill and realtime sync
tgcli server         Run background sync service (MCP optional); stop, restart, logs
tgcli service        Install/start/stop/status/logs for background service
tgcli channels       List/search channels
tgcli messages       List/search messages
tgcli send           Send text or files
tgcli media          Download media
tgcli topics         Forum topics
tgcli tags           Channel tags
tgcli metadata       Channel metadata cache
tgcli contacts       Contacts and people
tgcli groups         Group management
tgcli doctor         Diagnostics and sanity checks

Commands run through tgcli server, which the CLI starts on demand. After an upgrade, the next command of any kind replaces a server the CLI started itself, as soon as its backfill queue is empty. A server you started yourself with tgcli server or tgcli service keeps running the old code until you restart it; the CLI warns about this on stderr. tgcli server restart restarts the server on the CLI's version, tgcli server stop stops it, and tgcli server logs --follow shows its log.

Use tgcli [command] --help for details. Add --json for machine-readable output.

Once a day tgcli checks npm for a newer release in the background and, at a terminal, prints one line on stderr with the upgrade command (brew update && brew upgrade tgcli or npm i -g @kfastov/tgcli). Set TGCLI_NO_UPDATE_CHECK=1 to turn it off; see docs/cli.md.

MCP (optional)

Enable it via config:

tgcli config set mcp.enabled true

By default the server binds to http://127.0.0.1:8080/mcp. To change it:

tgcli config set mcp.host 127.0.0.1
tgcli config set mcp.port 8080

Then run tgcli server and point your client at the configured address.

Configuration & Store

The tgcli store lives in the OS app-data directory and contains config.json, sessions, and messages.db. Override the location with TGCLI_STORE.

Legacy version: see MIGRATION.md.

Development

Run it from a clone with Node 22: npm ci, then node cli.js. See docs/development.md for tests and for trying a change on your own account.

Read full README

tgcli MCP questions

How do I enable the MCP server in tgcli?

Set mcp.enabled to true through the config command, then run tgcli server and point your client at the configured address.

What authentication does tgcli use for Telegram?

It uses Telegram API credentials (api_id and api_hash) from my.telegram.org plus the tgcli auth command for session setup.

Can tgcli search message history offline?

Yes, it archives messages through sync and can search them from the local archive.

Does tgcli use the bot API?

No, it works with your personal Telegram account over MTProto rather than the bot API.

Facts

Nov 13, 2026

Stars: 45
Downloads, 30 days: —
Latest version: —
Last commit: Nov 12, 2026
License: MIT
Transport: —
Package: —

kfastov ↗

Community publisher

Published by an independent maintainer.

Alternatives

Works with

Claude Code Cursor VS Code Claude Desktop Codex Gemini CLI Windsurf Devin

Badge for your README

Show your HostedMCP checks score. The badge links readers to install instructions for every client.

[![HostedMCP checks](https://api.hostedmcp.org/v1/badge/server/kfastov/tgcli.svg)](https://hostedmcp.org/servers/kfastov/tgcli/checks)

Maintainer?

Claim this listing to edit it and add the HostedMCP badge to your README.

Claim listing

Before you install

Servers run with the permissions you give them. Use the narrowest token or database role that does the job.

About tgcli MCP server

What you can do with it

1Search archived messagesAsk the AI to find a specific piece of information within your archived Telegram history.
2Send Telegram messagesInstruct your AI client to send a text message or a file to a specific contact or username.
3Download media filesHave the AI retrieve and download media content from your Telegram chats.
4Manage forum topicsUse the AI to navigate or interact with specific topics within Telegram forums.

Written from the project's README. Every use case is checked against a quote from it.

tgcli auth tgcli sync --follow tgcli messages list --chat @username --limit 20 tgcli messages search "course" --chat @channel --source archive tgcli send text --to @username --message "hello" tgcli server

tgcli auth Authentication and session setup tgcli config View and edit config tgcli sync Archive backfill and realtime sync tgcli server Run background sync service (MCP optional); stop, restart, logs tgcli service Install/start/stop/status/logs for background service tgcli channels List/search channels tgcli messages List/search messages tgcli send Send text or files tgcli media Download media tgcli topics Forum topics tgcli tags Channel tags tgcli metadata Channel metadata cache tgcli contacts Contacts and people tgcli groups Group management tgcli doctor Diagnostics and sanity checks

tgcli MCP questions

How do I enable the MCP server in tgcli?

Set mcp.enabled to true through the config command, then run tgcli server and point your client at the configured address.

What authentication does tgcli use for Telegram?

It uses Telegram API credentials (api_id and api_hash) from my.telegram.org plus the tgcli auth command for session setup.

Can tgcli search message history offline?

Yes, it archives messages through sync and can search them from the local archive.

Does tgcli use the bot API?

No, it works with your personal Telegram account over MTProto rather than the bot API.