MCPPing

Ultra-lightweight MCP (Model Context Protocol) client for Telegram notifications. Connects to remote MCPPing-server via HTTP proxy. Perfect for use with Claude Desktop and other MCP clients.

Features

• 🚀 Fast startup - Under 2 seconds
• 📦 Ultra-minimal footprint - ~5MB installed (MCP client)
• 🔧 Simple configuration - Chat ID registration with remote bot
• 📱 Core Telegram features - Send notifications via HTTP proxy
• 🔗 HTTP Proxy - Connects to remote MCPPing-server instances
• 🛡️ Type safe - Full TypeScript support

Installation

NPX (Recommended)

npx @zanz9/mcpping

Quick Setup

1. Install Package

# Install the package (or it will be installed automatically when first used)
npx @zanz9/mcpping --version

2. Register with Remote Bot

# 1. Send /start to @mcpping_bot on Telegram
# 2. Bot will reply with your chat ID
# 3. Remember your chat ID - it will be saved automatically on first use

3. MCP Client Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mcpping": {
      "command": "npx",
      "args": ["@zanz9/mcpping"]
    }
  }
}

Add to your .mcp.json:

{
  "mcpServers": {
    "mcpping": {
      "command": "npx",
      "args": ["@zanz9/mcpping"]
    }
  }
}

Add to your .cursorrules or project config:

{
  "mcpServers": {
    "mcpping": {
      "command": "npx",
      "args": ["@zanz9/mcpping"]
    }
  }
}

4. Automatic Notifications with Hooks (Optional)

What are hooks? Hooks are scripts that run automatically at specific events (like when Claude finishes a task or ends a session). They can automatically send MCPPing notifications without manual intervention.

Add to your Claude Code settings JSON:

{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx @zanz9/mcpping --hook --summary"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "npx @zanz9/mcpping --hook --message 'File modified: completed task'"
          }
        ]
      }
    ]
  }
}

What this does:

• SessionEnd: Automatically sends session summary when Claude finishes
• PostToolUse: Sends notification after file modifications (Write/Edit tools)

⚠️ Important: Hooks execute shell commands automatically. Only use trusted configurations and understand what each command does before enabling hooks.

5. CLAUDE.md Session Summary (Alternative)

Add to your project's CLAUDE.md for manual session summaries:

## Session Summary Rule

- Always send notification to telegram using MCP server [@zanz9/mcpping] after completing tasks

### Summary sending rule:

ALWAYS use mcp**mcpping**send_telegram_notification at the end of session with the following format:

✅ **Completed tasks:**

- [list of tasks from todo list]
- [specific changes]

📁 **Modified files:** [list]
⏱️ **Working time:** [approximate estimate]
🎯 **Status:** [result]

### When to send:

- ✅ **ALWAYS** at the end of any session
- ✅ After completing ANY task or request
- ✅ Even if only answering questions or providing information
- ✅ When user says goodbye or ends conversation
- ✅ After any file modifications or code changes

Configuration

Chat ID Registration

The client connects to a remote server. To receive notifications:

1. Find the bot: @mcpping_bot on Telegram
2. Start conversation: Send /start to @mcpping_bot on Telegram
3. Get your chat ID: The bot will respond with your chat ID
4. First use: Chat ID will be saved automatically when you send your first notification

# The first time you send a notification with chat_id, it gets saved automatically
# After that, no chat_id parameter needed - it uses the saved one

# Verify setup
npx @zanz9/mcpping --version

Available MCP Tools

Core Tools

1. send_telegram_notification - Send text notifications via HTTP proxy
2. configure_chat_id - Set up your Telegram chat ID locally

The client acts as an MCP proxy, forwarding all requests to a remote MCPPing-server instance.

Architecture

Claude Desktop → MCPPing Client → HTTP Request → Remote Server → Telegram Bot → Your Chat

The client:

• Receives MCP requests from Claude Desktop
• Forwards them to remote MCPPing-server via HTTP
• Includes your chat ID in the request
• Returns responses back to Claude Desktop

Usage Examples

Basic Notification

{
  "tool": "send_telegram_notification",
  "arguments": {
    "message": "Task completed successfully!",
    "chat_id": "123456789"
  }
}

Note: Include chat_id for first-time setup. After that, it's optional - the saved chat ID will be used automatically.

Configure Chat ID

{
  "tool": "configure_chat_id",
  "arguments": {
    "chat_id": "123456789"
  }
}

Getting Started

1. Find the Bot: @mcpping_bot on Telegram
2. Register: Send /start to @mcpping_bot to register your chat
3. Get Chat ID: The bot will reply with your chat ID
4. Configure Claude: Add to claude_desktop_config.json
5. First use: Include your chat ID in the first notification - it gets saved automatically
6. Start using: All subsequent notifications work without chat ID