# Telegram MCP server

> Lets an AI client read, search, review and send messages on your own Telegram account, with per-profile write limits.

- Repository: https://github.com/WireCatLabs/tg-cli
- Page: https://hostedmcp.org/servers/wirecatlabs/tg-cli
- Transport: stdio
- Stars: 16
- License: Apache-2.0
- Latest version: 0.130.0

## Install

### Claude Code

```sh
claude mcp add tg-cli -- npx -y @wirecat/tg-cli
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "tg-cli": {
      "command": "npx",
      "args": [
        "-y",
        "@wirecat/tg-cli"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "tg-cli": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@wirecat/tg-cli"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"tg-cli","type":"stdio","command":"npx","args":["-y","@wirecat/tg-cli"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "tg-cli": {
      "command": "npx",
      "args": [
        "-y",
        "@wirecat/tg-cli"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add tg-cli -- npx -y @wirecat/tg-cli
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.tg-cli]
command = "npx"
args = ["-y", "@wirecat/tg-cli"]
```

### Gemini CLI

```sh
gemini mcp add -s user tg-cli npx -- -y @wirecat/tg-cli
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "tg-cli": {
      "command": "npx",
      "args": [
        "-y",
        "@wirecat/tg-cli"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `TG_PROFILE` | no | no |  |

## FAQ

### Does it work with my own Telegram account rather than a bot?

Yes, it logs in as one of your devices over MTProto using a Telegram app you register yourself, so it sees all your chats and history.

### How does an MCP client connect to Telegram through this?

Run the MCP server command and add the generated config entry to Claude Desktop, Cursor or another MCP client.

### Can the agent send messages, and are there limits?

Sending is possible but gated: a profile decides which chats it may send to and how many messages an hour, 30 by default.

### Does searching messages send my query to Telegram?

By default search covers the local copy and Telegram's server search; use --offline to keep the query on your computer.

### Does reading messages mark them as read?

No, reading leaves everything unread and the inbox command marks nothing read.
