tg-id-mcp

tg-id-mcp

MCP server for Telegram user/chat lookup with datacenter detection and account age estimation.

Works with Claude Code, Claude Desktop, and any MCP-compatible client.

Features

| Tool | Description | |------|-------------| | user_info | Look up any user, group, or channel by @username or numeric ID | | dc_detect | Detect which Telegram datacenter (DC1-DC5) hosts an account | | estimate_age | Estimate when an account was created based on its ID | | send_message | Send a message via your Telegram bot | | check_membership | Check if a user is a member/admin/banned in a chat | | get_me | Verify bot connection and capabilities | | dc_map | Get the full datacenter location map |

Datacenter Detection

Telegram assigns each account to one of 5 datacenters at registration. This server extracts the DC from the user's profile photo file_id — a technique not available through the standard Bot API.

| DC | Location | Typical regions | |----|----------|-----------------| | DC1 | Miami, USA | Early accounts, Americas | | DC2 | Amsterdam, NL | Europe, CIS | | DC3 | Miami, USA | Americas (expansion) | | DC4 | Amsterdam, NL | Europe (expansion) | | DC5 | Singapore, SG | Asia-Pacific |

Account Age Estimation

Telegram IDs are assigned roughly sequentially. Using known reference points (2013–2025), this server estimates when an account was created with ±2-3 month accuracy, and assigns a badge:

• Veteran — 10+ years (2013–2015)
• Experienced — 5-10 years (2016–2020)
• Seasoned — 2-5 years (2021–2023)
• Regular — 1-2 years
• Newcomer — < 1 year

Quick Start

Claude Code

claude mcp add tg-id-mcp -e TELEGRAM_BOT_TOKEN=YOUR_TOKEN -- uvx tg-id-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "tg-id-mcp": {
      "command": "uvx",
      "args": ["tg-id-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "YOUR_BOT_TOKEN"
      }
    }
  }
}

From source (development)

git clone https://github.com/barkoszloy/tg-id-mcp.git
cd tg-id-mcp
uv run tg-id-mcp

Getting a Bot Token

1. Open @BotFather in Telegram
2. Send /newbot and follow the prompts
3. Copy the token (looks like 123456789:ABCdefGHIjklMNO...)

Usage Examples

Once connected, ask Claude:

• "Look up @durov on Telegram"
• "What datacenter is user 123456789 on?"
• "How old is Telegram account 777000?"
• "Send 'Hello!' to chat -1001234567890"
• "Is user 123456789 a member of @mychannel?"

How It Works

Datacenter detection decodes the base64 file_id from a user's profile photo. Byte 4 in the decoded structure contains the DC number (1-5). This works because Telegram stores files on the same DC as the account.

Age estimation uses a lookup table of 41 known ID→date reference points, collected from public research and early account screenshots. The table maps ID ranges to approximate registration months from August 2013 to December 2024.

Related

• @usergtidbot — Telegram bot with the same features + visual ID cards, QR codes, username history, inline mode
• GitHub

License

MIT