MCP Telegram Server

A Model Context Protocol (MCP) server that provides tools for interacting with Telegram channels, groups, and private conversations on behalf of a user. This server allows MCP clients to retrieve recent messages, search messages, get chat information, and manage conversations.

Features

• Get Recent Messages: Retrieve the most recent messages from channels, groups, or private chats
• Get Private Messages: Dedicated tool for reading private conversation messages with enhanced formatting
• Search Messages: Search for specific content within channels, groups, or private conversations
• Get Chat Info: Retrieve metadata and information about any Telegram chat (channels, groups, private)
• Get Available Channels: List all channels and groups that the user has access to
• Mark Messages as Read: Mark specific messages or all messages as read in conversations
• Check Unread Messages: Find chats with unread messages in private conversations and groups
• Get Chat Status: Diagnostic tool to check read status and chat capabilities
• User Authentication: Works on behalf of the authenticated user (not bot tokens)

Prerequisites

1. Telegram API Credentials: You need to obtain API credentials from Telegram:

   • Go to https://my.telegram.org/apps
   • Log in with your phone number
   • Create a new application to get api_id and api_hash

2. User Session: You need to generate a session string for user authentication (see setup instructions below)

Installation

1. Install dependencies:

npm install

2. Build the project:

npm run build

Setup

1. Environment Variables

Create a .env file or set the following environment variables:

export TELEGRAM_API_ID="your_api_id"
export TELEGRAM_API_HASH="your_api_hash"
export TELEGRAM_SESSION="your_session_string"

2. Generate Session String

To generate a session string, you can create a simple script:

import { TelegramClient } from "telegram";
import { StringSession } from "telegram/sessions/index.js";
import input from "input";

const apiId = parseInt(process.env.TELEGRAM_API_ID!);
const apiHash = process.env.TELEGRAM_API_HASH!;

const session = new StringSession("");
const client = new TelegramClient(session, apiId, apiHash, {
  connectionRetries: 5,
});

(async () => {
  await client.start({
    phoneNumber: async () => await input.text("Enter your phone number: "),
    password: async () => await input.text("Enter your password: "),
    phoneCode: async () => await input.text("Enter the code you received: "),
    onError: (err) => console.log(err),
  });
  
  console.log("Session string:", client.session.save());
  console.log("Save this session string as TELEGRAM_SESSION environment variable");
  
  await client.disconnect();
})();

Usage

Running the Server

Start the MCP server:

npm start

The server communicates via stdio and can be used with any MCP client.

Available Tools

1. get_recent_messages

Retrieves recent messages from a Telegram channel, group, or private chat.

Parameters:

• channel (string, required): Channel username (@channelname), group username, private chat username (@username), phone number (+1234567890), or chat ID
• limit (number, optional): Number of messages to retrieve (default: 10, max: 100)
• sinceMinutes (number, optional): Get messages from the last N minutes
• sinceHours (number, optional): Get messages from the last N hours
• sinceDate (string, optional): Get messages since this date (ISO format: 2023-12-01T10:00:00Z)

Examples:

Get 20 most recent messages from a channel:

{
  "name": "get_recent_messages",
  "arguments": {
    "channel": "@examplechannel",
    "limit": 20
  }
}

Get messages from a private chat:

{
  "name": "get_recent_messages",
  "arguments": {
    "channel": "@username",
    "limit": 15
  }
}

Get messages from the last 30 minutes:

{
  "name": "get_recent_messages",
  "arguments": {
    "channel": "@examplechannel",
    "sinceMinutes": 30
  }
}

2. get_private_messages

Dedicated tool for retrieving messages from private chat conversations with enhanced formatting.

Parameters:

• contact (string, required): Contact identifier: username (@username), phone number (+1234567890), or user ID
• limit (number, optional): Number of messages to retrieve (default: 10, max: 100)
• sinceMinutes (number, optional): Get messages from the last N minutes
• sinceHours (number, optional): Get messages from the last N hours
• sinceDate (string, optional): Get messages since this date (ISO format: 2023-12-01T10:00:00Z)

Examples:

Get messages from a private chat by username:

{
  "name": "get_private_messages",
  "arguments": {
    "contact": "@username",
    "limit": 20
  }
}

Get messages from a contact by phone number:

{
  "name": "get_private_messages",
  "arguments": {
    "contact": "+1234567890",
    "limit": 10
  }
}

Get recent private messages from the last hour:

{
  "name": "get_private_messages",
  "arguments": {
    "contact": "@username",
    "sinceHours": 1
  }
}

3. get_channel_info

Retrieves information about a Telegram channel, group, or private chat.

Parameters:

• channel (string, required): Channel username (@channelname), group username, private chat username (@username), phone number (+1234567890), or chat ID

Examples:

Get channel information:

{
  "name": "get_channel_info",
  "arguments": {
    "channel": "@examplechannel"
  }
}

Get private chat information:

{
  "name": "get_channel_info",
  "arguments": {
    "channel": "@username"
  }
}

4. search_messages

Searches for messages containing specific text in a channel, group, or private chat.

Parameters:

• channel (string, required): Channel username (@channelname), group username, private chat username (@username), phone number (+1234567890), or chat ID
• query (string, required): Search query
• limit (number, optional): Number of results (default: 10, max: 100)
• sinceMinutes (number, optional): Search messages from the last N minutes
• sinceHours (number, optional): Search messages from the last N hours
• sinceDate (string, optional): Search messages since this date (ISO format: 2023-12-01T10:00:00Z)

Examples:

Search in a channel:

{
  "name": "search_messages",
  "arguments": {
    "channel": "@examplechannel",
    "query": "important announcement",
    "limit": 15
  }
}

Search in a private chat:

{
  "name": "search_messages",
  "arguments": {
    "channel": "@username",
    "query": "meeting",
    "limit": 10
  }
}

Search messages from the last hour:

{
  "name": "search_messages",
  "arguments": {
    "channel": "@examplechannel",
    "query": "update",
    "sinceHours": 1
  }
}

5. get_available_channels

Lists all channels and groups that the user has access to.

Parameters:

• limit (number, optional): Number of channels to retrieve (default: 50, max: 200)
• includeGroups (boolean, optional): Include groups in addition to channels (default: false)

Example:

{
  "name": "get_available_channels",
  "arguments": {
    "limit": 100,
    "includeGroups": true
  }
}

6. mark_messages_read

Mark messages as read in a Telegram chat, group, or private conversation.

Parameters:

• channel (string, required): Channel username, group username, private chat username (@username), phone number (+1234567890), or chat ID
• messageIds (array of numbers, optional): Specific message IDs to mark as read
• maxId (number, optional): Mark all messages up to this message ID as read

Important Note: This feature works with groups, supergroups, and private chats. Broadcast channels don't support read status operations due to Telegram API limitations.

Examples:

Mark specific messages as read in a group:

{
  "name": "mark_messages_read",
  "arguments": {
    "channel": "@examplegroup",
    "messageIds": [123, 124, 125]
  }
}

Mark messages as read in a private chat:

{
  "name": "mark_messages_read",
  "arguments": {
    "channel": "@username"
  }
}

Mark all messages up to a specific ID as read:

{
  "name": "mark_messages_read",
  "arguments": {
    "channel": "@examplegroup",
    "maxId": 150
  }
}

7. check_unread_messages

Check for unread messages in private chats and groups.

Parameters:

• limit (number, optional): Number of chats to check (default: 50, max: 200)
• includeChannels (boolean, optional): Include channels in addition to private chats and groups (default: false)
• onlyWithUnread (boolean, optional): Only return chats with unread messages (default: true)

Examples:

Check for unread messages in private chats and groups:

{
  "name": "check_unread_messages",
  "arguments": {
    "limit": 100
  }
}

Include channels and show all chats (even with no unread messages):

{
  "name": "check_unread_messages",
  "arguments": {
    "limit": 50,
    "includeChannels": true,
    "onlyWithUnread": false
  }
}

Check only chats with unread messages:

{
  "name": "check_unread_messages",
  "arguments": {
    "onlyWithUnread": true
  }
}

8. get_chat_status

Get detailed status information about a chat including unread count, read status, and diagnostic information.

Parameters:

• chat (string, required): Chat identifier: username (@username), phone number (+1234567890), or chat ID

Examples:

Get status of a private chat:

{
  "name": "get_chat_status",
  "arguments": {
    "chat": "@username"
  }
}

Get status of a group:

{
  "name": "get_chat_status",
  "arguments": {
    "chat": "@groupname"
  }
}

Note: This tool is particularly useful for debugging read status issues and understanding why mark_messages_read might not work as expected.

MCP Client Configuration

To use this server with an MCP client, add it to your client configuration:

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["/path/to/mcp-telegram-server/dist/index.js"],
      "env": {
        "TELEGRAM_API_ID": "your_api_id",
        "TELEGRAM_API_HASH": "your_api_hash",
        "TELEGRAM_SESSION": "your_session_string"
      }
    }
  }
}

Development

For development with auto-reload:

npm run dev

To watch for changes and rebuild:

npm run watch

Security Notes

• Session Security: Keep your session string secure. It provides full access to your Telegram account.
• API Credentials: Never share your API ID and hash publicly.
• Channel Access: The server can only access channels that your Telegram account has permission to read.
• Rate Limiting: Telegram has rate limits. The server doesn't implement rate limiting, so use responsibly.

Troubleshooting

1. Authentication Errors: Make sure your session string is valid and not expired.
2. Channel Access: Ensure your account has access to the channels you're trying to read.
3. API Limits: If you encounter rate limits, wait before making more requests.
4. Network Issues: The server includes connection retry logic, but network issues may still cause failures.
5. Mark Messages Read Issues:
   • If mark_messages_read returns success but messages aren't actually marked as read, use get_chat_status to debug
   • Some private chats may have restrictions on read status operations
   • Encrypted chats (secret chats) don't support read status marking via API
   • The function works best with regular groups and supergroups

Debugging Read Status Issues

If mark_messages_read isn't working:

1. Check chat status first:

   "Get status information for my chat with @username"
   

2. Verify chat type: The tool shows whether the chat supports read status operations

3. Check unread count: Use check_unread_messages to see if the operation actually worked

4. Try different approaches: The server automatically tries multiple API methods for private chats

License

MIT License