mcp-telegram

mcp-telegram

1
communicationai_chatbot

MCP Telegram is a TypeScript-based server designed to facilitate communication with Telegram using the MTProto protocol. It provides tools and CLI commands to automate Telegram interactions and includes integration with FastMCP for AI model compatibility.

MCP Telegram

A TypeScript implementation of an MCP (Model Context Protocol) server for working with Telegram through MTProto, built using FastMCP.

Overview

This project provides a set of tools for interacting with Telegram through the MTProto protocol, making them available via an MCP server for use with AI models like Claude.

Installation

# Install dependencies
npm install

# Build the project
npm run build

Usage

CLI Commands

The application provides the following CLI commands:

# Sign in to Telegram
npm run sign-in
# or
npx mcp-telegram sign-in

# Start the MCP server
npm run mcp
# or 
npx mcp-telegram mcp [options]

# Logout from Telegram
npm run logout
# or
npx mcp-telegram logout

CLI Options for the mcp command:

  • -t, --transport <type>: Transport type (stdio, sse), defaults to 'stdio'
  • -p, --port <number>: Port for HTTP/SSE transport, defaults to 3000
  • -e, --endpoint <path>: Endpoint for SSE transport, defaults to 'mcp'

Starting the MCP Server

Start the MCP server with stdio transport (default, used by Cursor AI):

npm run start
# or
npm run mcp

You can also run the server programmatically:

import server, { startServer } from 'mcp-telegram';

// Start the server with the configuration
startServer(server);

Environment Variables

The application uses the following environment variables:

  • TELEGRAM_API_ID: Your Telegram API ID
  • TELEGRAM_API_HASH: Your Telegram API Hash
  • TRANSPORT_TYPE: Transport type ('stdio', 'http', or 'sse'), defaults to 'stdio'
  • PORT: Port for HTTP or SSE transports, defaults to 3000
  • ENDPOINT: Endpoint for SSE transport, defaults to 'mcp'
  • LOG_LEVEL: Logging level, defaults to 'info'

These can be set in a .env file in the project root.

Development

Development requires Node.js version 18 or higher.

# Run in development mode
npm run dev

# Lint the code
npm run lint

# Run tests
npm run test

FastMCP Integration

The server is implemented using FastMCP, which provides a modern TypeScript implementation of the Model Context Protocol. It supports stdio and SSE transports, making it compatible with different client integration approaches.

Server Transports

  • stdio: Default transport, useful for direct integration with tools like Cursor AI
  • sse: Server-Sent Events transport for real-time communication

Available Tools

listDialogs

List available dialogs, chats and channels.

Parameters:

  • unread: Boolean, show only unread dialogs (default: false)
  • archived: Boolean, include archived dialogs (default: false)
  • ignorePinned: Boolean, ignore pinned dialogs (default: false)

listMessages

List messages in a given dialog, chat or channel.

Parameters:

  • dialogId: String, ID of the dialog to list messages from
  • unread: Boolean, show only unread messages (default: false)
  • limit: Number, maximum number of messages to retrieve (default: 100)

Project Structure

src/
├── config.ts               # Application configuration
├── index.ts                # Main server implementation
├── mcp.ts                  # CLI entry point
├── tools/                  # Tool implementations
│   ├── index.ts            # Tools export
│   └── telegramTools.ts    # Telegram tools
├── lib/           # Core Telegram functionality
│   ├── index.ts            # Module exports
│   ├── telegram.ts         # Telegram client functionality
└── utils/                  # Utilities
    ├── errorHandler.ts     # Error handling utilities
    └── logger.ts           # Logging utility

License

This project is licensed under the MIT License - see the LICENSE file for details.