innervoice/BEGINNER-GUIDE.md

Complete Beginner's Guide

Never used an MCP server before? Start here!

What Is This?

This lets Claude send you messages on Telegram (the messaging app on your phone). Claude can:

• Send you notifications when tasks finish
• Ask you questions and wait for your answer
• Check messages you send to it

Think of it like giving Claude a phone number to text you.

What You Need

Before starting, make sure you have:

• Telegram app installed on your phone (Get it here)
• Claude Code or Claude Desktop installed
• Basic terminal/command line knowledge (how to run commands)
• 10 minutes of setup time

Step-by-Step Setup

Part 1: Create a Telegram Bot (5 minutes)

A "bot" is like a robot contact in Telegram that your computer can control.

1. Open Telegram on your phone or computer

2. Search for @BotFather (this is Telegram's official bot-making bot)

3. Start a chat with BotFather and send this message:

   /newbot
   

4. BotFather will ask you questions:

   Question: "Alright, a new bot. How are we going to call it?" → Answer: My Claude Assistant (or any name you want)

   Question: "Good. Now let's choose a username" → Answer: my_claude_bot_123 (must end in bot and be unique)

5. BotFather gives you a token - It looks like this:

   123456789:ABCdefGHIjklMNOpqrsTUVwxyz-1234567890
   

   IMPORTANT: Copy this token! You'll need it in a minute. Keep it secret - anyone with this token can control your bot!

6. Find your bot in Telegram search and open a chat with it (It won't respond yet - that's normal!)

Part 2: Install the Bridge (3 minutes)

Now we install the software that connects Claude to your Telegram bot.

1. Download this project:

   Option A: If you have git:

   git clone https://github.com/RichardDillman/claude-telegram-bridge.git
   cd claude-telegram-bridge
   

   Option B: No git?

   • Go to https://github.com/RichardDillman/claude-telegram-bridge
   • Click green "Code" button → "Download ZIP"
   • Unzip it
   • Open terminal in that folder

2. Install dependencies:

   pnpm install
   

   Don't have pnpm? Install it first:

   npm install -g pnpm
   

   Don't have npm? Install Node.js (it includes npm)

3. Set up your bot token:

   cp .env.example .env
   

   Now edit .env file (use any text editor):

   • Replace your_bot_token_here with the token BotFather gave you
   • Save the file

4. Build and start the bridge:

   pnpm build
   pnpm dev
   

   You should see: 🤖 Telegram bot started

   Keep this terminal window open! The bridge needs to stay running.

5. Activate your bot:

   • Go to Telegram
   • Find the chat with your bot
   • Send this message: /start
   • Bot should reply with "Claude Telegram Bridge Active"

   ✅ Your bridge is now working!

Part 3: Connect Claude to the Bridge (2 minutes)

Now we tell Claude about your Telegram bridge.

1. Find where your bridge is installed:

   Open a NEW terminal window (keep the first one running!) and type:

   cd claude-telegram-bridge
   pwd
   

   Copy the output - it's your "bridge path" Example: /Users/yourname/claude-telegram-bridge

2. Create or edit your MCP config file:

   For Claude Code (CLI):

   Create a file at: ~/.config/claude-code/settings/mcp.json

   Don't know how? Run this:

   mkdir -p ~/.config/claude-code/settings
   nano ~/.config/claude-code/settings/mcp.json
   

   For Claude Desktop:

   Already have settings → skip to next step

3. Add this configuration:

   Paste this (replace /path/to/... with your bridge path from step 1):

   {
     "mcpServers": {
       "telegram": {
         "command": "node",
         "args": [
           "/path/to/claude-telegram-bridge/dist/mcp-server.js"
         ]
       }
     }
   }
   

   Real example:

   {
     "mcpServers": {
       "telegram": {
         "command": "node",
         "args": [
           "/Users/john/claude-telegram-bridge/dist/mcp-server.js"
         ]
       }
     }
   }
   

   Save the file (Ctrl+O, Enter, Ctrl+X in nano)

4. Restart Claude Code or Claude Desktop

Testing It Out

Now let's make sure everything works!

1. Open Claude (CLI or Desktop)

2. Ask Claude to test it:

   Type this to Claude:

   Send me a test notification via Telegram
   

3. Check your phone - You should get a Telegram message!

4. If it worked: 🎉 You're done! Claude can now message you.

5. If it didn't work: See troubleshooting below

What Can Claude Do Now?

Tell Claude things like:

• "When you finish running the tests, send me a notification"
• "If there are any errors, ask me via Telegram what to do"
• "Check if I've sent you any messages on Telegram"

Claude will automatically use the Telegram tools when appropriate!

Troubleshooting

"Bridge not running" or "Connection refused"

Problem: The bridge stopped or never started

Fix:

cd claude-telegram-bridge
pnpm dev

Keep this terminal open!

Want it to run in background?

pnpm daemon  # Starts in background
pnpm logs    # View logs
pnpm stop    # Stop it

"Tool not found" or "MCP server not found"

Problem: Path in config is wrong

Fix:

1. Find the correct path:

   cd claude-telegram-bridge
   pwd
   ls dist/mcp-server.js  # Should say "dist/mcp-server.js"
   

2. Update your MCP config with the correct path

3. Restart Claude

"No Telegram messages"

Problem: Bot not initialized

Fix:

1. Open Telegram
2. Find your bot
3. Send: /start
4. Try again

"Token is wrong" or "Unauthorized"

Problem: Bot token is incorrect

Fix:

1. Go back to BotFather in Telegram
2. Send: /mybots
3. Select your bot → "API Token"
4. Copy the new token
5. Update .env file
6. Restart bridge: pnpm dev

Keeping It Running

Every time you restart your computer:

The bridge stops! You need to start it again:

cd claude-telegram-bridge
pnpm daemon  # Runs in background

Check if it's running:

curl http://localhost:3456/health

Should show: {"status":"running"...}

Next Steps

• Read README.md for advanced features
• See CONTRIBUTING.md to customize the bridge
• Check MCP Protocol docs to learn more about MCP

Still Stuck?

1. Check the Issues: https://github.com/RichardDillman/claude-telegram-bridge/issues
2. Open a new issue with:
   • What step you're on
   • Error message (if any)
   • What you tried

We'll help you get it working!