https://github.com/kfastov/telegram-mcp-server
MCP server implementation for Telegram
https://github.com/kfastov/telegram-mcp-server
ai-agents fastmcp mcp mcp-server telegram telegram-client
Last synced: 5 months ago
JSON representation
MCP server implementation for Telegram
- Host: GitHub
- URL: https://github.com/kfastov/telegram-mcp-server
- Owner: kfastov
- License: mit
- Created: 2025-03-19T14:48:50.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-01-26T10:06:10.000Z (5 months ago)
- Last Synced: 2026-01-27T00:20:25.194Z (5 months ago)
- Topics: ai-agents, fastmcp, mcp, mcp-server, telegram, telegram-client
- Language: JavaScript
- Homepage:
- Size: 324 KB
- Stars: 29
- Watchers: 1
- Forks: 13
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
- metorial-index - Telegram Client Library and MCP Server - Interact with Telegram channels and messages, enabling searches for channels and retrieval of messages using regex patterns. It utilizes the user client API for comprehensive access to Telegram's features. (Social Media)
- toolsdk-mcp-registry - ❌ telegram-channel-explorer
README
# tgcli
**Revival update (September 2025).** The server now runs on the official `@modelcontextprotocol/sdk` transport, backed by the MtCute Telegram client and a sequential background archive worker writing into SQLite.
**Breaking changes.** MCP clients must target `http://localhost:8080/mcp`; message history now lives in the tgcli store, and new sync tools drive archival jobs. The legacy implementation remains published as branch `legacy-0.x` and tag `v0-legacy` if you need the old `/sse` flow.
**Key changes:** `/mcp` endpoint, MtCute session handling, message-sync job queue, SQLite archive, CLI workflows in `tgcli` (auth/sync/diagnostics/media).
See [MIGRATION.md](MIGRATION.md) for v1→v2 changes.
tgcli is an MCP server allowing AI assistants (like Claude or Cursor) to interact with your Telegram account using the user client API (not the bot API). The stack rides on the official `@modelcontextprotocol/sdk` Streamable HTTP transport and exposes Telegram-oriented tools for listing dialogs, fetching messages, and managing background sync jobs.
## MCP Tools (current)
- Dialogs: `listChannels`, `searchChannels`, `listActiveChannels`.
- Tags + metadata: `setChannelTags`, `listChannelTags`, `listTaggedChannels`, `autoTagChannels`, `refreshChannelMetadata`, `getChannelMetadata`.
- Topics: `topicsList`, `topicsSearch` (use `messagesList` with `topicId` for messages).
- Messages: `messagesList`, `messagesSearch`, `messagesGet`, `messagesContext`.
- Send + media: `messagesSend`, `messagesSendFile`, `mediaDownload`.
- Sync: `scheduleMessageSync`, `listMessageSyncJobs`, `getSyncedMessageStats`.
- Contacts: `contactsSearch`, `contactsGet`, `contactsAliasSet`, `contactsAliasRemove`, `contactsTagsAdd`, `contactsTagsRemove`, `contactsNotesSet`.
- Groups: `groupsList`, `groupsInfo`, `groupsRename`, `groupsMembersAdd`, `groupsMembersRemove`, `groupsInviteLinkGet`, `groupsInviteLinkRevoke`, `groupsJoin`, `groupsLeave`.
## Prerequisites
1. **Node.js:** Version 18 or later recommended.
2. **Telegram Account:**
- You need an active Telegram account.
- **Two-Step Verification (2FA)** must be enabled on your account (Settings → Privacy and Security → Two-Step Verification).
3. **Telegram API Credentials:**
- Obtain an `api_id` and `api_hash` by creating a new application at [https://core.telegram.org/api/obtaining_api_id](https://core.telegram.org/api/obtaining_api_id).
## Install
### npm
```bash
npm install -g @kfastov/tgcli
```
### Homebrew
```bash
brew install kfastov/tap/tgcli
```
### From source
```bash
git clone https://github.com/your-username/telegram-mcp-server.git # Replace with your repo URL
cd telegram-mcp-server
npm install
```
## Configuration
There are two separate configurations that need to be set up:
1. **Telegram Credentials (tgcli store):**
Run `tgcli auth` and enter your API ID, API hash, and phone number. The credentials are saved to `config.json` inside the tgcli store directory.
2. **MCP Client Configuration:**
Configure client software (Claude Desktop, Cursor, etc.) to connect to the MCP server by modifying their configuration files:
```json
{
"mcpServers": {
"telegram": {
"url": "http://localhost:8080/mcp",
"disabled": false,
"timeout": 30
}
}
}
```
For Claude Desktop, the config file is located at:
- On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
**Important:** Restart your MCP client to apply the changes.
## Store Location
tgcli keeps the session, SQLite archive, and downloads in the OS app-data directory:
- macOS: `~/Library/Application Support/tgcli`
- Linux: `$XDG_DATA_HOME/tgcli` (fallback `~/.local/share/tgcli`)
- Windows: `%APPDATA%\\tgcli`
Override the location with `TGCLI_STORE`.
## Running the Server
```bash
tgcli auth
tgcli server
```
On the first run the server will authenticate via MTProto. Enter the login code from Telegram and (if enabled) your 2FA password. After a successful login a persistent session file is saved under `session.json` inside the tgcli store, so restarts won't prompt again unless the session is revoked.
You can still run the dev entrypoint directly:
```bash
npm start
```
## CLI
```bash
tgcli auth
tgcli sync --follow
tgcli doctor
tgcli channels list --limit 10
tgcli messages search "course" --chat -1001234567890 --source archive
tgcli send text --to @channel --message "hello"
tgcli media download --chat -1001234567890 --id 42
tgcli topics list --chat -1001234567890 --limit 20
tgcli tags set --chat -1001234567890 --tags ai,news
tgcli contacts search "alex"
tgcli groups list --query "Nha Trang"
```
Use `--json` for machine-readable output. Set `TGCLI_STORE` if you want to point the CLI to a different store location.
## Background Message Sync
- Jobs and archived messages are stored in `messages.db` inside the tgcli store (SQLite).
- Use `scheduleMessageSync` to enable backfill for a channel, then run the worker with `tgcli server` or `tgcli sync --follow`.
- The server processes sync jobs sequentially and waits between requests to avoid hitting Telegram rate limits.
- Use the MCP tools to manage jobs:
```
scheduleMessageSync { "channelId": -1001234567890, "minDate": "2024-01-01T00:00:00Z" }
listMessageSyncJobs {}
```
You can supply either the numeric chat ID or the public username as `channelId`. Jobs resume automatically when the server restarts. Job statuses transition through `pending → in_progress → idle`, moving to `error` if retries are required.
## Forum Topics
- List or search topics with `topicsList` and `topicsSearch`.
- Fetch topic messages using `messagesList` with `topicId` (and `source` set to `archive`, `live`, or `both`).
## Channel Tags & Cross-Channel Search
- Tag channels with `setChannelTags`, then retrieve them via `listTaggedChannels`.
- Use `refreshChannelMetadata` to cache descriptions, then `autoTagChannels` to auto-assign tags.
- Search across tagged channels with `messagesSearch`:
```
setChannelTags { "channelId": -1001234567890, "tags": ["ai"] }
autoTagChannels { "channelIds": [-1001234567890] }
messagesSearch { "tags": ["ai"], "query": "course OR курс", "fromDate": "2025-12-01T00:00:00Z" }
```
## Contacts & Groups
- Use the `contacts*` tools to manage aliases/tags/notes and look up user profiles.
- Use the `groups*` tools for listing, metadata, member management, and invite links (permissions required).
## Troubleshooting
- **Login Prompts:** If the server keeps prompting for login codes/passwords when started by the MCP client, ensure the `session.json` file exists inside the tgcli store. You might need to run `tgcli auth` or `tgcli server` manually once to refresh the session.
- **Store Lock:** If the CLI reports a lock, run `tgcli doctor` and ensure no other process is using the same store.
- **Cache Issues:** If channels seem outdated or missing, restart the server or call `refreshChannelMetadata`.
- **Cannot Find Module:** Ensure you run `npm install` in the project directory. If the MCP client starts the server, make sure the working directory is set correctly or use absolute paths.
- **Other Issues:** If you encounter any other problems, feel free to open an issue in [this server repo](https://github.com/kfastov/telegram-mcp-server).
## Telegram Client Library
This repository also contains the underlying `telegram-client.js` library used by the MCP server. For details on using the library directly (e.g., for custom scripting), see [LIBRARY.md](LIBRARY.md).
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.