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)

Related MCP server: MCP-Telegram

Features

• 10 MCP tools: folders, 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 tools

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

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