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