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

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

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

{
  "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.

{
  "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'"
          }
        ]
      }
    ]
  }
}

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