# GhostPaw Telegram MCP server

> Lets an AI client mirror, search, send, and moderate Telegram messages using a local SQLite database and structured tool facade.

- Repository: https://github.com/GhostPawJS/telegram
- Page: https://hostedmcp.org/servers/ghostpawjs/telegram
- Transport: stdio
- Stars: 1
- License: MIT
- Latest version: 0.7.9

## Install

### Claude Code

```sh
claude mcp add --env 'TELEGRAM_BOT_TOKEN=<YOUR_TELEGRAM_BOT_TOKEN>' telegram -- npx -y @ghostpaw/telegram
```

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

```json
{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": [
        "-y",
        "@ghostpaw/telegram"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "<YOUR_TELEGRAM_BOT_TOKEN>"
      }
    }
  }
}
```

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

```json
{
  "servers": {
    "telegram": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@ghostpaw/telegram"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "<YOUR_TELEGRAM_BOT_TOKEN>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"telegram","type":"stdio","command":"npx","args":["-y","@ghostpaw/telegram"],"env":{"TELEGRAM_BOT_TOKEN":"<YOUR_TELEGRAM_BOT_TOKEN>"}}'
```

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

```json
{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": [
        "-y",
        "@ghostpaw/telegram"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "<YOUR_TELEGRAM_BOT_TOKEN>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add telegram --env 'TELEGRAM_BOT_TOKEN=<YOUR_TELEGRAM_BOT_TOKEN>' -- npx -y @ghostpaw/telegram
```

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

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

[mcp_servers.telegram.env]
TELEGRAM_BOT_TOKEN = "<YOUR_TELEGRAM_BOT_TOKEN>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'TELEGRAM_BOT_TOKEN=<YOUR_TELEGRAM_BOT_TOKEN>' telegram npx -- -y @ghostpaw/telegram
```

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

```json
{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": [
        "-y",
        "@ghostpaw/telegram"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "<YOUR_TELEGRAM_BOT_TOKEN>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `TELEGRAM_BOT_TOKEN` | no | yes | Telegram Bot API token; enables send and moderation execution |
| `GHOSTPAW_TELEGRAM_DB` | no | no | SQLite database path (default: ~/.ghostpaw/telegram.db) |

## Tools (4)

- `tg_read`: Read and query the Telegram database: messages, chats, users, reactions, and more. Use when: Use when you need to inspect stored messages, find chats or users, search text, or retrieve reaction and edit history. Not for: Do not use for sending, editing, or deleting messages. (read-only)
- `tg_send`: Outbound actions: send, edit, delete, pin/unpin messages, send typing indicator, and forward messages. Use when: Plans only by default. Use createTelegramToolFacade with execute: true and a client to perform actions with configurable limits. Use when you need to send or modify messages, show a typing indicator, or forward a message to another chat. Not for: Do not use for reading or querying stored data.
- `tg_manage`: Moderation and chat administration: ban, unban, restrict, promote, kick users, and query member info. Use when: Plans only by default. Use createTelegramToolFacade with execute: true and a client to perform actions with configurable limits. Use when you need to moderate users, manage chat permissions, or look up member status. Not for: Do not use for sending messages or reading message history.
- `tg_connect`: Query bot connection status, configuration, and chat list. Use when: Use to retrieve bot statistics, stored state values, or a list of active chats. Not for: Do not use for sending messages or moderating users. (read-only)

## FAQ

### How does the server handle incoming Telegram updates?

Every incoming update is mirrored into a local SQLite database before the handler runs, providing a persistent and queryable record.

### Can I use the server without a Telegram bot token?

Yes, without a token, local reads and tool discovery work offline, and send/moderation tools will return plans instead of executing actions.

### Where is the message database stored?

By default, messages are stored in ~/.ghostpaw/telegram.db, but you can specify a custom path using the GHOSTPAW_TELEGRAM_DB environment variable or the --db flag.

### Does the server support media files?

Yes, it includes eager file BLOB storage for photos, documents, voice messages, and videos, which are downloaded in the background.
