tg-mcp-tools

A local MCP server for Cursor and Claude Desktop. 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?”

Install

npm install -g tg-mcp-tools

Or run without installing (recommended for MCP):

npx tg-mcp-tools-auth   # one-time login
npx tg-mcp-tools        # MCP server (stdio)

Features

• 13 MCP tools: channels (create/rename), folders (create/edit), dialogs, messages, digests, send message, archive/unarchive
• 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

Create a project directory, add credentials, authorize, then connect MCP.

mkdir my-telegram-mcp && cd my-telegram-mcp
cp path/to/node_modules/tg-mcp-tools/.env.example .env
# or from a git clone: cp .env.example .env

Fill in .env:

TELEGRAM_API_ID=12345678
TELEGRAM_API_HASH=your_api_hash

Authorize (scan QR in terminal; session is saved to .env in the current directory):

npx tg-mcp-tools-auth
# or, from a git clone: npm run auth

Verify the MCP server starts:

npx tg-mcp-tools
# or, from a git clone: npm run mcp

Cursor setup

Add to .cursor/mcp.json in your project (where .env lives):

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

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

For local development from a git clone, use:

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

After changing the config, reload Cursor (Developer: Reload Window).

MCP Inspector

Use the MCP Inspector to call tg_* tools in the browser and inspect JSON-RPC traffic before wiring Cursor.

From the project root (where .env lives):

npm run inspect

This builds the server, starts it via npm run mcp over stdio, and opens the Inspector UI (usually http://localhost:6274). Use the full URL printed in the terminal if an auth token is required.

Links

• MCP Inspector docs
• Inspector on GitHub
• @modelcontextprotocol/inspector on npm

CLI mode (no browser):

npx -y @modelcontextprotocol/inspector --cli npm run mcp

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_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 (@username or numeric id)
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 in Cursor:

What’s new in my Travel folder this week?

Authorization

1. Run npx tg-mcp-tools-auth from the directory where .env should live
2. On your phone: Telegram → Settings → Devices → Link Desktop Device
3. Scan the QR code in the terminal
4. Enter your 2FA password if prompted
5. TELEGRAM_SESSION is written to .env automatically

Scripts

Command	Description
npx tg-mcp-tools-auth	One-time login; saves TELEGRAM_SESSION to .env in cwd
npx tg-mcp-tools	Start the MCP server (stdio)
npm run auth / npm run mcp	Start auth or MCP server (npm run build first when developing from a git clone)
npm run inspect	Build and launch MCP Inspector for this server
npm run build	Compile TypeScript → dist/

Security

• Do not commit .env — it contains your Telegram session (full account access)
• Never share TELEGRAM_SESSION in logs, issues, or chats
• Revoke API credentials or sessions at my.telegram.org

Project layout

src/
├── config.ts           # load .env from repo root
├── env-file.ts         # update .env values after auth
├── telegram-client.ts  # mtcute: dialogs, history, post URLs
├── index.ts            # MCP server and tool registration
└── auth.ts             # CLI auth (QR)

Stack

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