Telegram MCP Tools

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

Related MCP server: Claudegram

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

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