MCP Telegram

🚀 MCP Telegram Protocol

This project is an MCP (Model Context Protocol) server implemented in TypeScript. It's designed to interact with Telegram via the MTProto protocol and is built using FastMCP. It offers a set of tools for interacting with Telegram through the MTProto protocol and making it accessible to AI models like Claude via the MCP server.

🚀 Quick Start

This project provides a set of tools to interact with Telegram via the MTProto protocol and make it available to AI models such as Claude through an MCP server.

📦 Installation

# Install dependencies
npm install

# Build the project
npm run build

💻 Usage Examples

Basic Usage

CLI Commands

The application provides the following CLI commands:

# Log 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]

# Log out of the Telegram account
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>: HTTP/SSE transport port, defaults to 3000
• -e, --endpoint <path>: Endpoint for SSE transport, defaults to 'mcp'

Starting the MCP Server

Start the MCP server using stdio transport (default, for tools like Cursor AI):

npm run start
# Or
npm run mcp

You can also start the server programmatically:

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

// Start the server with 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 transport, defaults to 3000
• ENDPOINT: Endpoint for SSE transport, defaults to 'mcp'
• LOG_LEVEL: Log level, defaults to 'info' These variables can be set in the .env file at the project root.

Advanced Usage

import { createServer } from 'mcp-telegram';

const server = createServer({
  port: 3000,
  endpoint: 'mcp',
  transportType: 'stdio'
});

server.start();

🔧 Technical Details

Development

Development requires Node.js version 18 or higher.

# Run in development mode
npm run dev

# Format the code
npm run lint

# Run tests
npm run test

FastMCP Integration

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

Server Transports

• stdio: Default transport, suitable 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 specified 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 file
├── server.ts               # Server implementation
└── utils/                 # Utility functions
    └── logger.ts          # Logging utility

📚 Documentation

This documentation explains how to use the MCP protocol to interact with Telegram and provides complete code examples and configuration options.