tgcli

Telegram user console client and archiver

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

Command

claude mcp add --transport stdio kfastov-tgcli npx -y @kfastov/tgcli \
  --env TGCLI_STORE="path/to/store (optional)" \
  --env TELEGRAM_API_ID="your_api_id" \
  --env TELEGRAM_API_HASH="your_api_hash"

How to use

tgcli is a Telegram command-line interface that can operate as a personal MTProto client with optional background MCP server support. The tool provides authentication against Telegram, local synchronization of messages, and a suite of commands to browse, search, send, and manage Telegram data. When enabling the MCP server, tgcli exposes an HTTP API (default: http://127.0.0.1:8080/mcp) that client applications can use to trigger sync tasks, read message metadata, or interact with the stored session data. Start by authenticating with Telegram, then configure MCP if you want remote access to the session data. The available commands include authentication, syncing, listing and sending messages, managing channels, media, and many utilities for diagnostics and configuration. To use MCP, enable it in your tgcli config and then start the server with tgcli server; your client can then point to the configured host/port for MCP access.

How to install

Prerequisites:

Node.js (LTS) and npm installed on your machine
Optional: Homebrew on macOS for convenient tgcli installation

Installation steps:

Install the CLI globally via npm: npm install -g @kfastov/tgcli
(macOS) Optional Homebrew installation of the CLI tap: brew install kfastov/tap/tgcli
Authenticate with Telegram (will prompt for API credentials): tgcli auth
Start using tgcli commands (examples): tgcli sync --follow tgcli messages list --chat @username --limit 20 tgcli send text --to @username --message "hello"
Enable and run MCP server (optional): tgcli config set mcp.enabled true tgcli server
Point your MCP client to the configured address (default http://127.0.0.1:8080/mcp) and begin interacting with the session data.

Additional notes

Tips and notes:

The MCP server is optional and is accessed after tgcli config mcp.enabled is set to true. The default bind is http://127.0.0.1:8080/mcp; adjust host/port in config as needed.
TGCLI_STORE environment variable can override the OS-specific app-data store location for config, sessions, and messages.
Ensure your Telegram API credentials (api_id and api_hash) are kept secret and never shared.
If you encounter port conflicts, choose a different host/port in the tgcli config before starting the MCP server.
Logs from the MCP server can help with debugging; check tgcli logs and system logs if running as a background service.

Related MCP Servers

ai-dev-tools-zoomcamp

986

AI Dev Tools Zoomcamp is a free course that helps you use AI tools to write better code, faster. We're starting the first cohort of this course on November 18, 2025! Sign up here to join us 👇🏼

ai-trader

491

Backtrader-powered backtesting framework for algorithmic trading, featuring 20+ strategies, multi-market support, CLI tools, and an integrated MCP server for professional traders.

shinzo-ts

TypeScript SDK for MCP server observability, built on OpenTelemetry. Gain insight into agent usage patterns, contextualize tool calls, and analyze server performance across platforms. Integrate with any OpenTelemetry ingest service including the Shinzo platform.

lichess

A Model Context Protocol (MCP) server that enables Claude Desktop to interact with Lichess chess platform through natural language. Play games, analyze positions, manage your account, and participate in tournaments—all by simply talking to Claude.

ultrafast

High-performance, ergonomic Model Context Protocol (MCP) implementation in Rust

mcp-document-converter

MCP Document Converter - A powerful MCP tool for converting documents between multiple formats, enabling AI agents to easily transform documents.