Tg Tools

npm version License: MIT Node.js

A local MCP server for Cursor, Claude, Codex, or any other client. It reads your Telegram subscriptions over MTProto (personal account, not a bot) and exposes channel posts to the agent for digests and natural-language questions like “what’s new in my Travel folder this week?”

Features

• 21 MCP tools across domains: channels (create/rename/join/leave/discover/search), subscriptions (list/archive/mute), folders, messages, send
• Post links — every message includes a url field (https://t.me/...)
• Archived channels — included when listing subscriptions
• QR login — scan from the terminal, no SMS or in-app codes

Requirements

• Node.js 18+
• Telegram API credentials from my.telegram.org/apps

Quick start (npm package)

Use this path if you consume the published package — no git clone needed.

1. Create a project directory and install the package

mkdir my-telegram-mcp && cd my-telegram-mcp
npm install tg-mcp
cp node_modules/tg-mcp/.env.example .env

2. Add API credentials to .env

TELEGRAM_API_ID=12345678
TELEGRAM_API_HASH=your_api_hash

3. Authorize (QR in terminal; session is saved to .env)

npx tg-mcp-auth

On your phone: Telegram → Settings → Devices → Link Desktop Device → scan the QR code. TELEGRAM_SESSION is written to .env automatically.

4. Connect MCP

Cursor

Add to .cursor/mcp.json in the same directory as .env:

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "tg-mcp"]
    }
  }
}

The server loads .env from the current working directory (your project root). You don't need to duplicate env vars in mcp.json.

Reload Cursor after changing the config (Developer: Reload Window).

Claude Desktop

Open the config file: Settings → Developer → Edit Config

Add a telegram entry under mcpServers. Put credentials in env — Claude Desktop does not load .env from disk:

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "tg-mcp"],
      "env": {
        "TELEGRAM_API_ID": "12345678",
        "TELEGRAM_API_HASH": "your_api_hash",
        "TELEGRAM_SESSION": "your_session_string"
      }
    }
  }
}

Copy the three values from .env after npx tg-mcp-auth. If you re-authorize, update TELEGRAM_SESSION here too.

Fully quit Claude Desktop (system tray → Exit), then relaunch. The connector appears under Connectors.

---

Development (git clone)

Use this path if you work from the repository — local src/, rebuilds, and MCP Inspector.

1. Clone and install

git clone https://github.com/ausievich/tg-mcp-tools.git
cd tg-mcp-tools
npm install
cp .env.example .env

2. Add API credentials to .env (same as above)

3. Build and authorize

npm run build
npm run auth

4. Connect MCP

Cursor

{
  "mcpServers": {
    "telegram": {
      "command": "npm",
      "args": ["run", "mcp"]
    }
  }
}

Run npm run build after code changes. npm run inspect builds and opens MCP Inspector for interactive tool testing.

---

MCP tools

Tool	Purpose
tg_create_channel	Create a new broadcast channel (title and optional description)
tg_set_channel_title	Rename a channel or group (requires admin rights)
tg_get_similar_channels	Telegram-recommended similar public channels (by channel, folder, or all subscriptions)
tg_search_channels	Global search for public channels/groups by name or post content
tg_join_channel	Subscribe to a channel/group by @username, id, or invite link
tg_leave_channel	Unsubscribe from a channel or leave a group
tg_mute_chats	Mute notifications for chats/channels (forever by default)
tg_unmute_chats	Restore notifications for muted chats/channels
tg_get_folders	Telegram chat folders (tabs) with id and name
tg_create_folder	Create a folder with channels and filter rules
tg_edit_folder	Update an existing folder: replace included chats or rename it
tg_get_dialogs	List channels, groups, and chats; optional folder filter
tg_get_messages	Posts from one channel; pagination (beforeMessageId), date filters (sinceHours, minDate)
tg_get_post_comments	Comments on a channel post by t.me URL or channelId + messageId; pagination (offsetId, offsetDate)
tg_search_messages	Full-text search in one chat across entire history
tg_search_in_folder	Search by text across all channels/groups in a folder
tg_get_recent_from_channels	Digest from multiple channels, sorted by date
tg_get_recent_from_folder	Digest from all channels/groups in a folder
tg_send_message	Send formatted text to a user (@username), chat id, or "me" (Markdown/HTML)
tg_archive_chats	Move chats/channels to Archive
tg_unarchive_chats	Restore chats/channels from Archive

Example prompts:

What’s new in my Travel folder this week?

Get all comments on https://t.me/channel/123 and summarize the discussion

Security

• Do not commit .env — it contains your Telegram session (full account access)
• Claude Desktop / Codex: config files with inline env hold the same secrets as .env — treat them like .env
• Never share TELEGRAM_SESSION in logs, issues, or chats
• Revoke API credentials or sessions at my.telegram.org
• Log out locally: npx tg-mcp-logout (npm) or npm run logout (git clone)

Stack

• @mtcute/node — MTProto client
• @modelcontextprotocol/sdk — MCP
• TypeScript (ESM), zod, dotenv