# tg-id-mcp

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

Works with [Claude Code](https://claude.com/claude-code), [Claude Desktop](https://claude.ai/download), 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

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

### Claude Desktop

Add to `claude_desktop_config.json`:

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

### From source (development)

```bash
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](https://t.me/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](https://t.me/usergtidbot) — Telegram bot with the same features + visual ID cards, QR codes, username history, inline mode
- [GitHub](https://github.com/barkoszloy/tg-id-mcp)

## License

MIT