# tg-cli [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/WireCatLabs/tg-cli  
**GitHub Stars:** 12  
**npm Downloads (last month):** 7502  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/tg-cli

## Description
Telegram CLI for AI agents — your whole account in the terminal, local-first search, MCP server and full Bot API.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "tg-cli": {
    "command": "npx",
    "args": ["-y","@wirecat/tg-cli"]
  }
}
```

## Documentation

## What tg-cli does

tg-cli gives AI agents access to a personal Telegram account as if it were another logged-in device. It uses Telegram’s MTProto API for client applications, so it can work with chats, groups, channels, contacts, and account history instead of being limited to bot-owned conversations.

The MCP interface is intended for clients that do not directly run terminal commands. Agents can use it to catch up on unread messages, review recent conversations, search messages, inspect group activity, draft or send replies, and work with files and voice messages. Ready-made prompts include `/catch-up`, `/review`, `/reply`, `/find`, `/open-tasks`, and `/link-conversations`.

Search is local-first: content that has been read is stored on the computer. A normal search can also query Telegram’s own search service, while `--offline` limits the query to the local copy. Reading operations do not mark messages as read.

## How it works

The command-line entry point is `tg`. Terminal-based agents such as Claude Code, Codex, and Gemini CLI can run its commands directly, using the bundled agent skill to learn the available workflows. MCP clients connect through `tg personal mcp` instead.

Telegram access uses an app registered by the account owner at `my.telegram.org/apps`. The setup flow logs in by QR code, checks the first chats, and can install the agent skill. Older history is downloaded separately. The server can also use the full Telegram Bot API, including all 185 methods, alongside personal-account commands.

A profile controls what an agent may do. It can limit available actions, restrict which chats may receive messages, and impose a message rate limit of 30 messages per hour by default. Sending is not enabled automatically when an MCP profile is first added; the profile must be reviewed and writes explicitly allowed.

## Setup and configuration

Install the package globally with npm, Bun, or another documented package-manager path:

```sh
npm install -g @wirecat/tg-cli
tg personal setup
tg personal mcp add claude-code
tg personal mcp config
```

Use `tg personal mcp add codex` for Codex, or generate the configuration entry with `tg personal mcp config` for Claude Desktop, Cursor, and other MCP clients. Install the agent skill for terminal agents with `tg skill install --for all`.

The setup requires Node.js 22.16 or newer, Node.js 24 or newer, or Bun, and runs on macOS, Linux, and Windows. `npx @wirecat/tg-cli --help` provides a no-install way to inspect the command-line help. The account owner supplies the Telegram app credentials during setup and completes QR-code login.

## Tools and capabilities

- List chats and messages, including message context and unread messages across chats.
- Review messages since the previous review or within a date range.
- Search local message data and optionally Telegram’s server-side search.
- Inspect group activity, including joins, leaves, additions, and removals.
- Send, edit, forward, pin, schedule, or delete messages; add reactions and create polls.
- Send replies, files, photos, videos, and voice messages.
- Download message files and transcribe voice messages using Telegram Premium transcription or a locally run speech model.
- Manage contacts, account aliases and notes, blocked contacts, and logged-in devices.

## Limitations and notes

This integration acts as the logged-in user, not as a Telegram bot, and requires a user-registered Telegram application. Downloading older history is a separate operation from initial setup. Local search only covers content that has been read and stored on the computer; server search is used by default unless `--offline` is selected.

Write operations require deliberate profile configuration. The default rate limit is 30 messages per hour, and the profile can narrow the chats an agent may contact. If Telegram’s send result is uncertain, tg-cli reports the uncertainty and provides a repeat command designed to avoid delivering the message twice. npm may warn about blocked install scripts for the package or `better-sqlite3`; the setup notes indicate that these scripts do not need to be allowed.

_Full upstream README: https://allmcps.com/mcp/tg-cli/readme_