Telegram

🚀 Telegram MCP Server

This is a server for interacting with the Telegram API via the Model Context Protocol (MCP). It enables AI agents and other MCP clients to interact with Telegram.

🚀 Quick Start

✨ Features

• Enables interaction between AI agents and other MCP clients with Telegram through the Model Context Protocol (MCP).

📦 Installation

• Requirements:
  • Node.js 14+
  • npm
  • Telegram API ID and API hash

1. Clone the repository:

   git clone https://github.com/kdoronin/telegram_mcp
   cd telegram-mcp
   

2. Install dependencies:

   npm install
   

   (This will install necessary packages such as gramjs, @modelcontextprotocol/sdk, zod, etc.)

3. Create and configure the .env file:

   # Copy the example .env file
   cp .env.example .env
   

   Edit the .env file and specify your API_ID and API_HASH in it.

4. Obtain API ID and API hash: Refer to How to get Telegram API ID and API hash.

💻 Usage Examples

Basic Usage

// Example: Get updates
await executeTool({
  toolName: "getUpdates",
  parameters: {
    offset: null,
    limit: 10,
    timeout: 0
  }
});

📚 Documentation

Running the Server

After installation, run the server from the project root directory:

npm run mcp

The first time you run it, you'll be prompted to enter your Telegram account phone number, 2FA password (if any), and Telegram password (if any).

Integration

Integration in Cursor

1. Open Cursor and go to Settings.
2. Navigate to the MCP Server section.
3. Click Add MCP Server and enter the following information:
   • Name: Telegram
   • Type: URL
   • Address: http://localhost:3000

Integration in Claude Desktop

1. Open Claude Desktop and go to Settings.
2. Navigate to the MCP Server section.
3. Click Add MCP Server and enter the following information:
   • Name: Telegram
   • Type: URL
   • Address: http://localhost:3000

Functionality Check

After running the server, you can test the MCP server by accessing http://localhost:3000.

Available Tools

The following is a list of tools supported by the MCP server:

1. executeCode
2. getFiles
3. getGptModels
4. getImages
5. getUpdates
6. initialize
7. setOptions

Authorization

• The first time you run the server, you'll be prompted to enter your Telegram account phone number, 2FA password (if any), and Telegram password (if any).
• If authorization fails, you can delete the session file in the sessions/ directory and try again.

Session File Structure

Session files are stored in the sessions/ directory, with the file name being the phone number (e.g., +79001234567.json). Each file contains:

• Encrypted session string
• Creation/Update timestamp

Troubleshooting

1. Error "Your API ID or Hash cannot be empty or undefined"

   • Check if the .env file is in the project root directory.
   • Ensure that API_ID and API_HASH are correctly filled in.
   • Run the server from the project root directory.

2. Server does not recognize the saved session

   • Check the execution path (should be the project root directory).
   • Check if the session file in the sessions/ directory exists.
   • Try running with npm run mcp.

3. Authorization error

   • If you enter the wrong 2FA password, the system will prompt you to re - enter it.
   • If all attempts fail, delete the session file and try again.

🔧 Technical Details

The server uses the Model Context Protocol (MCP) to interact with the Telegram API. It relies on Node.js and several npm packages such as gramjs, @modelcontextprotocol/sdk, and zod to implement its functionality.

📄 License

This project is licensed under the MIT license.

⚠️ Important Note

• Do not share your API ID and hash with third parties.
• Run the server in a trusted environment.
• Session files contain sensitive data. Keep them secure and do not share them.
• The executeMethod tool can execute any Telegram API method. Use it with caution as it may perform destructive operations.