Log inSubmit server
Tg Cli logo

Tg Cli

Connects AI agents to a personal Telegram account for local-first search, message workflows, and controlled reads and writes.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Tg Cli

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "tg-cli": {
      "command": "npx",
      "args": [
        "-y",
        "@wirecat/tg-cli"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

tg-cli MCP server connects AI agents to a personal Telegram account through Telegram’s MTProto client API. It supports local-first search, inbox and review workflows, chat and message operations, and controlled account actions through `tg personal mcp`. Reach for it when an agent needs access to personal chats, groups, channels, contacts, and history rather than only Telegram bot conversations. Profiles can restrict writes, permitted chats, and message frequency.

Use cases

  • Catch up on unread Telegram messages across chats
  • Search local and server-side Telegram history
  • Review unanswered questions and pending commitments
  • Send controlled replies, files, and scheduled messages
  • Inspect group membership and recent activity

Key features

  • Personal Telegram account access over MTProto
  • Local-first message search with offline mode
  • MCP interface for desktop and coding agents
  • Inbox, review, chat, and message workflows
  • Profile-based write permissions and rate limits
  • Telegram Bot API support with 185 methods

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 3d ago

Recent health check succeeded.

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 6d ago via OSV.dev · @wirecat/tg-cli (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars12Stargazers on the source repository.
npm downloads7.5kPackage downloads in the last 30 days.
Last commit3d agoMost recent push to the default branch.

How Tg Cli works

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:

Terminal
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.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Tg Cli

tg-cli is an MCP server that connects AI agents to a personal Telegram account through Telegram’s MTProto API. Its main tools cover inbox and review workflows, local and server-side message search, chat and message operations, and controlled sending. It works with the user’s chats, groups, channels, contacts, and account history.

Install it with `npm install -g @wirecat/tg-cli`, then run `tg personal setup` to register or connect a Telegram app and log in by QR code. Add the MCP configuration with `tg personal mcp config`, or use `tg personal mcp add` for a supported client.

Yes, tg-cli works with Cursor through its MCP configuration. Run `tg personal mcp config` to obtain the configuration entry, then add it to Cursor. Review the profile before enabling writes because MCP profiles can send messages when write permissions are allowed.

Yes, tg-cli can restrict searches to the message data stored on the computer by using `--offline`. Without that flag, searches also query Telegram’s own search service. Local search covers content that has already been read and saved locally.

Review the MCP profile and rerun the client setup with `--allow-writes` to enable sending. Profiles can restrict permitted chats and message frequency, with a default limit of 30 messages per hour. Reading does not mark messages as read.

Related MCP servers

All in Communication All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewTg Cli AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/tg-cli?style=directory)](https://allmcps.com/mcp/tg-cli)
HTML Embed
<a href="https://allmcps.com/mcp/tg-cli"><img src="https://allmcps.com/api/badge/tg-cli?style=directory" alt="Tg Cli on AllMCPs" /></a>