innervoice/USAGE.md

Telegram MCP Server - Usage Guide

What You've Built

You now have a standardized MCP (Model Context Protocol) server that any Claude instance can use to communicate with you via Telegram!

How It Works

Architecture

┌─────────────────┐      ┌──────────────────┐      ┌─────────────┐
│  Claude Code    │◄────►│  MCP Server      │◄────►│  HTTP API   │
│  (any instance) │      │  (stdio protocol)│      │  (:3456)    │
└─────────────────┘      └──────────────────┘      └──────┬──────┘
                                                            │
                                                            ▼
                                                    ┌───────────────┐
                                                    │  Telegram Bot │
                                                    │  (Telegraf)   │
                                                    └───────┬───────┘
                                                            │
                                                            ▼
                                                    ┌───────────────┐
                                                    │   Your Phone  │
                                                    │   (Telegram)  │
                                                    └───────────────┘

Two Components

1. HTTP Bridge (pnpm dev) - Always running service that communicates with Telegram
2. MCP Server (auto-started by Claude) - Translates Claude's tool calls to HTTP requests

Installation Steps

1. Build the Project

cd claude-telegram-bridge
pnpm install
pnpm build

2. Start the Bridge Service

# Option 1: Development mode (foreground)
pnpm dev

# Option 2: Production mode (background daemon)
pnpm daemon

# Check daemon logs
pnpm logs

# Stop daemon
pnpm stop

3. Configure Your Claude Code MCP Settings

Location: ~/.config/claude-code/settings/mcp.json (or Claude Desktop settings)

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/claude-telegram-bridge/dist/mcp-server.js"
      ],
      "env": {
        "TELEGRAM_BRIDGE_URL": "http://localhost:3456"
      }
    }
  }
}

Replace /ABSOLUTE/PATH/TO/ with your actual installation path!

To find your path:

cd claude-telegram-bridge
pwd
# Use the output + /dist/mcp-server.js

4. Initialize Your Telegram Bot

1. Open Telegram on your phone
2. Search for your bot (get username from BotFather)
3. Send /start to the bot
4. The bot will save your chat ID automatically

Using the MCP Server

Once configured, Claude will have access to these tools automatically:

Example 1: Simple Notification

You say:

"When you finish installing the packages, send me a notification via Telegram"

Claude will:

// Claude automatically uses:
telegram_notify({
  message: "✅ All packages installed successfully!",
  priority: "success"
})

You receive in Telegram:

✅ All packages installed successfully!

---

Example 2: Ask for Approval

You say:

"Run the database migration, but ask me for confirmation before applying it"

Claude will:

// Step 1: Prepare migration
// ...

// Step 2: Ask for approval
const answer = await telegram_ask({
  question: "Database migration ready. Apply now? (yes/no)"
})

// Step 3: Proceed based on your answer
if (answer.toLowerCase() === 'yes') {
  // Apply migration
}

You receive in Telegram:

❓ Database migration ready. Apply now? (yes/no)

You reply:

yes

Claude receives your answer and continues

---

Example 3: Check for Messages

You say:

"Check if I've sent you any messages via Telegram"

Claude will:

// Claude uses:
telegram_get_messages({})

// Then reports back to you in the chat

---

Example 4: Health Check

You say:

"Is the Telegram bridge working?"

Claude will:

// Claude uses:
telegram_check_health({})

// Returns status, unread messages, etc.

Available Tools

Tool	Purpose	Blocks?
telegram_notify	Send notification	No
telegram_ask	Ask question, wait for answer	Yes (5 min timeout)
telegram_get_messages	Get unread messages	No
telegram_reply	Reply to message	No
telegram_check_health	Check bridge status	No

Best Practices

When Claude Should Use These Tools

1. Long-running operations - Notify when complete
2. Critical decisions - Ask for approval via telegram_ask
3. Background tasks - Update progress periodically
4. Errors that need attention - Send error notifications
5. User input needed - Ask questions when uncertain

Example Workflow

User: "Scrape the ESO website and notify me when done"

Claude thinks:
  1. Start scraping
  2. Every 100 items → telegram_notify({ message: "Progress: 100 items scraped" })
  3. If error → telegram_notify({ message: "Error occurred", priority: "error" })
  4. When complete → telegram_notify({ message: "Scraping complete!", priority: "success" })

Troubleshooting

Bridge Not Running

curl http://localhost:3456/health

If no response:

pnpm dev  # Start the bridge

MCP Server Not Found

Check the path in your MCP config:

cd claude-telegram-bridge
ls dist/mcp-server.js

Update the path in mcp.json if needed.

Chat ID Not Set

Message your bot with /start in Telegram.

Testing the Tools Manually

Test the HTTP API directly:

# Test notification
curl -X POST http://localhost:3456/notify \
  -H "Content-Type: application/json" \
  -d '{"message": "Test!", "priority": "info"}'

# Check health
curl http://localhost:3456/health

Sharing with Other Claude Instances

Now that this is an MCP server, you can grant access to:

• Claude Code (CLI)
• Claude Desktop
• Other MCP-compatible clients

Just add the same configuration to their MCP settings!

Environment Variables

# .env file
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=auto_set_on_start
PORT=3456
HOST=localhost
ENABLED=true
TELEGRAM_BRIDGE_URL=http://localhost:3456  # For MCP server

Security Notes

• The bridge runs on localhost:3456 by default
• Only accessible from your machine
• Your Telegram bot token is in .env (keep it secret!)
• Chat ID is saved after you send /start

Next Steps

1. Start the bridge: pnpm dev
2. Add to Claude Code MCP config
3. Restart Claude Code
4. Test: "Send me a test notification via Telegram"
5. Enjoy real-time communication with Claude!