ausievich/tg-mcp-tools

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