# telegram-tools MCP server

> Allows an AI client to manage Telegram chats, send messages, download files, and perform message actions like editing or reacting.

- Repository: https://github.com/craft-agent/telegram-tools
- Page: https://hostedmcp.org/servers/craft-agent/telegram-tools
- Transport: stdio
- Stars: 0
- Latest version: 0.5.1

## Install

### Claude Code

```sh
claude mcp add telegram-tools -- npx -y @craftsamo/telegram-tools
```

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

```json
{
  "mcpServers": {
    "telegram-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@craftsamo/telegram-tools"
      ]
    }
  }
}
```

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

```json
{
  "servers": {
    "telegram-tools": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@craftsamo/telegram-tools"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"telegram-tools","type":"stdio","command":"npx","args":["-y","@craftsamo/telegram-tools"]}'
```

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

```json
{
  "mcpServers": {
    "telegram-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@craftsamo/telegram-tools"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add telegram-tools -- npx -y @craftsamo/telegram-tools
```

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

```toml
[mcp_servers.telegram-tools]
command = "npx"
args = ["-y", "@craftsamo/telegram-tools"]
```

### Gemini CLI

```sh
gemini mcp add -s user telegram-tools npx -- -y @craftsamo/telegram-tools
```

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

```json
{
  "mcpServers": {
    "telegram-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@craftsamo/telegram-tools"
      ]
    }
  }
}
```

## Tools (13)

- `telegram_account_read`
- `telegram_chat_read`
- `telegram_sync_read`
- `telegram_sync_add`
- `telegram_sync_remove`
- `telegram_message_send`
- `telegram_file_save`
- `telegram_file_send`
- `telegram_message_edit`
- `telegram_message_delete`
- `telegram_message_react`
- `telegram_message_pin`
- `telegram_chat_mark_read`

## FAQ

### Can the server send files via Telegram?

Yes, it can send between 1 and 10 files (up to 100 MB total) with a caption to a chat.

### Does the server require a phone number or API key to be provided in the results?

No, the account tool reads local state only and does not include phone numbers, account IDs, or keys in its output.

### How are received files stored?

Files are saved in a specific directory structure: <download_dir>/<label>/<chat id>/<message id>/ with private permissions.
