mcpField
C
claude-ops-telegram-server

claude-ops-telegram-server

Local
github.com/Lifecycle-Innovations-LimitedCommunication547Updated today
Repository

About claude-ops-telegram-server

claude-ops Telegram MCP Server is a user-auth MCP server that signs in as a personal Telegram account via MTProto (gram.js) rather than as a bot. It supports the /ops:ops-inbox skill and can read and reply to direct message conversations.

Key features

  1. 01Personal account authentication via MTProto
  2. 02List recent conversations with unread counts
  3. 03Fetch messages from a specific chat
  4. 04Full-text search across all conversations

Use cases

  1. 01Reading and replying to personal Telegram DMs
  2. 02Checking unread messages across chats
  3. 03Searching past messages across all conversations

MCP support

The project is an MCP server that runs over stdio and exposes four tools, list_dialogs, get_messages, send_message and search_messages, to MCP clients such as Claude Code.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "auroracapital-claude-ops-telegram-server": {
      "command": "npx",
      "args": [
        "-y",
        "claude-ops-telegram-server"
      ],
      "env": {
        "TELEGRAM_API_ID": "<TELEGRAM_API_ID>",
        "TELEGRAM_API_HASH": "<TELEGRAM_API_HASH>",
        "TELEGRAM_PHONE": "<TELEGRAM_PHONE>",
        "TELEGRAM_SESSION": "<TELEGRAM_SESSION>"
      }
    }
  }
}
Run commandnpx -y claude-ops-telegram-server
Environment variables to set
TELEGRAM_API_IDSecretNumeric API ID from https://my.telegram.org/apps (create a personal app, not a bot).
TELEGRAM_API_HASHSecretAPI hash from the same my.telegram.org/apps page.
TELEGRAM_PHONESecretYour Telegram phone number in E.164 format (e.g. +14155551234).
TELEGRAM_SESSIONSecretgram.js StringSession token. Generate once via: node index.js --auth (prompts for SMS code + optional 2FA). Store in your secret manager — never commit.

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npmclaude-ops-telegram-server0.2.1

Tools

4

Saved tool list · updated 2w ago

ParameterTypeRequiredDescription
limitnumberNoMax dialogs to return (default 30, max 100)
archivedbooleanNoInclude archived dialogs (default false)

Details

From the project README

claude-ops Telegram MCP Server

User-auth Telegram MCP server for the /ops:ops-inbox skill. Authenticates as a personal Telegram account via MTProto (gram.js), not as a BotFather bot, so it can read and reply to real DM conversations.

Why user-auth, not bot?

Bots cannot read messages sent in private chats between two users — only messages sent directly to the bot. For the /ops:ops-inbox use case (managing the owner's personal inbox), we must authenticate as the user's account.

Setup

1. Get API credentials

Go to https://my.telegram.org/apps and create a personal application (not a bot). You'll get:

  • api_id (integer)
  • api_hash (32-char string)
2. Install dependencies
cd claude-ops/telegram-server
npm install
3. First-run authentication (interactive)
TELEGRAM_API_ID=12345 \
TELEGRAM_API_HASH=abcdef... \
TELEGRAM_PHONE=+15551234567 \
node index.js --auth

The script will prompt for an SMS code and (if enabled) your 2FA password. On success it prints a TELEGRAM_SESSION string — save this securely (it's your session token).

4. Configure MCP server in Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["/path/to/claude-ops/telegram-server/index.js"],
      "env": {
        "TELEGRAM_API_ID": "${TELEGRAM_API_ID}",
        "TELEGRAM_API_HASH": "${TELEGRAM_API_HASH}",
        "TELEGRAM_SESSION": "${TELEGRAM_SESSION}",
        "TELEGRAM_PHONE": "${TELEGRAM_PHONE}"
      }
    }
  }
}

Export the env vars from a secret manager (Doppler, 1Password, direnv — never commit):

export TELEGRAM_API_ID="..."
export TELEGRAM_API_HASH="..."
export TELEGRAM_SESSION="..."   # from step 3
export TELEGRAM_PHONE="+1..."
export TELEGRAM_ENABLED=true    # enables in ops-unread detection

Restart Claude Code to load the MCP server.

Tools

ToolDescription
list_dialogsList recent conversations (DMs, groups, channels) with unread counts
get_messagesFetch messages from a specific chat
send_messageSend a message to a chat or user
search_messagesFull-text search across all conversations

Security

  • Never commit TELEGRAM_SESSION — it's equivalent to your password
  • Session tokens are device-bound; if stolen, log out via Telegram app → Settings → Devices
  • All credentials come from environment variables; nothing is hardcoded in this repo
  • The server runs over stdio (local only); no network exposure beyond Telegram's official API

Troubleshooting

"Session is no longer valid": Re-run node index.js --auth to generate a fresh session.

"TELEGRAM_API_ID is required": The env vars aren't being passed to the MCP server. Check your ~/.claude/settings.json env block.

Rate limiting: Telegram enforces per-account limits. If you hit one, wait 15-30 minutes before retrying.

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.