telegram-claude-mcp 1.4.0 → 1.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +288 -0
- package/package.json +3 -2
- package/src/index.ts +1 -0
- package/src/providers/index.ts +3 -1
- package/src/telegram.ts +2 -2
package/README.md
ADDED
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
# telegram-claude-mcp
|
|
2
|
+
|
|
3
|
+
Get Telegram notifications from Claude Code with interactive permission buttons.
|
|
4
|
+
|
|
5
|
+
When Claude needs permission to run a command or access a file, you'll get a Telegram message with Allow/Deny buttons. When Claude finishes working, you can reply with more instructions to continue.
|
|
6
|
+
|
|
7
|
+
## Quick Start
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npx telegram-claude-setup
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Then:
|
|
14
|
+
1. Create a Telegram bot via [@BotFather](https://t.me/BotFather)
|
|
15
|
+
2. Get your chat ID (see instructions below)
|
|
16
|
+
3. Edit `~/.claude/settings.json` with your bot token and chat ID
|
|
17
|
+
4. Restart Claude Code
|
|
18
|
+
|
|
19
|
+
## Features
|
|
20
|
+
|
|
21
|
+
- **Permission buttons** - Allow/Deny tool usage from Telegram
|
|
22
|
+
- **Interactive stop** - Reply to continue Claude's work after it stops
|
|
23
|
+
- **Notifications** - Get notified about Claude events
|
|
24
|
+
- **Multi-session** - Run multiple Claude instances with message tagging
|
|
25
|
+
|
|
26
|
+
## Manual Installation
|
|
27
|
+
|
|
28
|
+
If you prefer not to use npm, follow these steps:
|
|
29
|
+
|
|
30
|
+
### 1. Create Hook Scripts
|
|
31
|
+
|
|
32
|
+
Create directory `~/.claude/hooks/` and add these scripts:
|
|
33
|
+
|
|
34
|
+
**~/.claude/hooks/permission-hook.sh**
|
|
35
|
+
```bash
|
|
36
|
+
#!/bin/bash
|
|
37
|
+
SESSION_DIR="/tmp/telegram-claude-sessions"
|
|
38
|
+
|
|
39
|
+
find_active_session() {
|
|
40
|
+
local latest_file=""
|
|
41
|
+
local latest_time=0
|
|
42
|
+
[ -d "$SESSION_DIR" ] || return
|
|
43
|
+
for info_file in "$SESSION_DIR"/*.info; do
|
|
44
|
+
[ -e "$info_file" ] || continue
|
|
45
|
+
local pid
|
|
46
|
+
pid=$(jq -r '.pid // empty' "$info_file" 2>/dev/null)
|
|
47
|
+
if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
|
|
48
|
+
local file_time
|
|
49
|
+
file_time=$(stat -f %m "$info_file" 2>/dev/null || stat -c %Y "$info_file" 2>/dev/null)
|
|
50
|
+
if [ "$file_time" -gt "$latest_time" ]; then
|
|
51
|
+
latest_time=$file_time
|
|
52
|
+
latest_file=$info_file
|
|
53
|
+
fi
|
|
54
|
+
fi
|
|
55
|
+
done
|
|
56
|
+
echo "$latest_file"
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
INFO_FILE=$(find_active_session)
|
|
60
|
+
[ -z "$INFO_FILE" ] || [ ! -f "$INFO_FILE" ] && exit 0
|
|
61
|
+
|
|
62
|
+
HOOK_PORT=$(jq -r '.port' "$INFO_FILE")
|
|
63
|
+
HOOK_HOST=$(jq -r '.host // "localhost"' "$INFO_FILE")
|
|
64
|
+
HOOK_URL="http://${HOOK_HOST}:${HOOK_PORT}/permission"
|
|
65
|
+
|
|
66
|
+
INPUT=$(cat)
|
|
67
|
+
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // .toolName // .name // empty')
|
|
68
|
+
TOOL_INPUT=$(echo "$INPUT" | jq -c '.tool_input // .toolInput // .input // .arguments // {}')
|
|
69
|
+
|
|
70
|
+
PAYLOAD=$(jq -n --arg tool_name "$TOOL_NAME" --argjson tool_input "$TOOL_INPUT" \
|
|
71
|
+
'{tool_name: $tool_name, tool_input: $tool_input}')
|
|
72
|
+
|
|
73
|
+
RESPONSE=$(curl -s -X POST "$HOOK_URL" -H "Content-Type: application/json" -d "$PAYLOAD" --max-time 600)
|
|
74
|
+
[ $? -eq 0 ] && echo "$RESPONSE"
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
**~/.claude/hooks/stop-hook.sh**
|
|
78
|
+
```bash
|
|
79
|
+
#!/bin/bash
|
|
80
|
+
SESSION_DIR="/tmp/telegram-claude-sessions"
|
|
81
|
+
|
|
82
|
+
find_active_session() {
|
|
83
|
+
local latest_file=""
|
|
84
|
+
local latest_time=0
|
|
85
|
+
[ -d "$SESSION_DIR" ] || return
|
|
86
|
+
for info_file in "$SESSION_DIR"/*.info; do
|
|
87
|
+
[ -e "$info_file" ] || continue
|
|
88
|
+
local pid
|
|
89
|
+
pid=$(jq -r '.pid // empty' "$info_file" 2>/dev/null)
|
|
90
|
+
if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
|
|
91
|
+
local file_time
|
|
92
|
+
file_time=$(stat -f %m "$info_file" 2>/dev/null || stat -c %Y "$info_file" 2>/dev/null)
|
|
93
|
+
if [ "$file_time" -gt "$latest_time" ]; then
|
|
94
|
+
latest_time=$file_time
|
|
95
|
+
latest_file=$info_file
|
|
96
|
+
fi
|
|
97
|
+
fi
|
|
98
|
+
done
|
|
99
|
+
echo "$latest_file"
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
INPUT=$(cat)
|
|
103
|
+
STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')
|
|
104
|
+
[ "$STOP_HOOK_ACTIVE" = "true" ] && exit 0
|
|
105
|
+
|
|
106
|
+
INFO_FILE=$(find_active_session)
|
|
107
|
+
[ -z "$INFO_FILE" ] || [ ! -f "$INFO_FILE" ] && exit 0
|
|
108
|
+
|
|
109
|
+
HOOK_PORT=$(jq -r '.port' "$INFO_FILE")
|
|
110
|
+
HOOK_HOST=$(jq -r '.host // "localhost"' "$INFO_FILE")
|
|
111
|
+
HOOK_URL="http://${HOOK_HOST}:${HOOK_PORT}/stop"
|
|
112
|
+
|
|
113
|
+
TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // empty')
|
|
114
|
+
PAYLOAD=$(jq -n --arg transcript_path "$TRANSCRIPT_PATH" '{transcript_path: $transcript_path}')
|
|
115
|
+
|
|
116
|
+
RESPONSE=$(curl -s -X POST "$HOOK_URL" -H "Content-Type: application/json" -d "$PAYLOAD" --max-time 300)
|
|
117
|
+
if [ $? -eq 0 ]; then
|
|
118
|
+
DECISION=$(echo "$RESPONSE" | jq -r '.decision // empty')
|
|
119
|
+
[ "$DECISION" = "block" ] && echo "$RESPONSE"
|
|
120
|
+
fi
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
**~/.claude/hooks/notify-hook.sh**
|
|
124
|
+
```bash
|
|
125
|
+
#!/bin/bash
|
|
126
|
+
SESSION_DIR="/tmp/telegram-claude-sessions"
|
|
127
|
+
|
|
128
|
+
find_active_session() {
|
|
129
|
+
local latest_file=""
|
|
130
|
+
local latest_time=0
|
|
131
|
+
[ -d "$SESSION_DIR" ] || return
|
|
132
|
+
for info_file in "$SESSION_DIR"/*.info; do
|
|
133
|
+
[ -e "$info_file" ] || continue
|
|
134
|
+
local pid
|
|
135
|
+
pid=$(jq -r '.pid // empty' "$info_file" 2>/dev/null)
|
|
136
|
+
if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
|
|
137
|
+
local file_time
|
|
138
|
+
file_time=$(stat -f %m "$info_file" 2>/dev/null || stat -c %Y "$info_file" 2>/dev/null)
|
|
139
|
+
if [ "$file_time" -gt "$latest_time" ]; then
|
|
140
|
+
latest_time=$file_time
|
|
141
|
+
latest_file=$info_file
|
|
142
|
+
fi
|
|
143
|
+
fi
|
|
144
|
+
done
|
|
145
|
+
echo "$latest_file"
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
INFO_FILE=$(find_active_session)
|
|
149
|
+
[ -z "$INFO_FILE" ] || [ ! -f "$INFO_FILE" ] && exit 0
|
|
150
|
+
|
|
151
|
+
HOOK_PORT=$(jq -r '.port' "$INFO_FILE")
|
|
152
|
+
HOOK_HOST=$(jq -r '.host // "localhost"' "$INFO_FILE")
|
|
153
|
+
HOOK_URL="http://${HOOK_HOST}:${HOOK_PORT}/notify"
|
|
154
|
+
|
|
155
|
+
INPUT=$(cat)
|
|
156
|
+
MESSAGE=$(echo "$INPUT" | jq -r '.message // "Notification"')
|
|
157
|
+
PAYLOAD=$(jq -n --arg type "notification" --arg message "$MESSAGE" '{type: $type, message: $message}')
|
|
158
|
+
|
|
159
|
+
curl -s -X POST "$HOOK_URL" -H "Content-Type: application/json" -d "$PAYLOAD" --max-time 10 >/dev/null 2>&1
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Make them executable:
|
|
163
|
+
```bash
|
|
164
|
+
chmod +x ~/.claude/hooks/*.sh
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### 2. Configure Claude Settings
|
|
168
|
+
|
|
169
|
+
Add to `~/.claude/settings.json`:
|
|
170
|
+
|
|
171
|
+
```json
|
|
172
|
+
{
|
|
173
|
+
"hooks": {
|
|
174
|
+
"PermissionRequest": [
|
|
175
|
+
{
|
|
176
|
+
"matcher": "*",
|
|
177
|
+
"hooks": [{ "type": "command", "command": "~/.claude/hooks/permission-hook.sh" }]
|
|
178
|
+
}
|
|
179
|
+
],
|
|
180
|
+
"Stop": [
|
|
181
|
+
{
|
|
182
|
+
"matcher": "*",
|
|
183
|
+
"hooks": [{ "type": "command", "command": "~/.claude/hooks/stop-hook.sh" }]
|
|
184
|
+
}
|
|
185
|
+
],
|
|
186
|
+
"Notification": [
|
|
187
|
+
{
|
|
188
|
+
"matcher": "*",
|
|
189
|
+
"hooks": [{ "type": "command", "command": "~/.claude/hooks/notify-hook.sh" }]
|
|
190
|
+
}
|
|
191
|
+
]
|
|
192
|
+
},
|
|
193
|
+
"mcpServers": {
|
|
194
|
+
"telegram": {
|
|
195
|
+
"command": "npx",
|
|
196
|
+
"args": ["-y", "telegram-claude-mcp"],
|
|
197
|
+
"env": {
|
|
198
|
+
"TELEGRAM_BOT_TOKEN": "YOUR_BOT_TOKEN",
|
|
199
|
+
"TELEGRAM_CHAT_ID": "YOUR_CHAT_ID",
|
|
200
|
+
"SESSION_NAME": "default"
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
### 3. Create Telegram Bot
|
|
208
|
+
|
|
209
|
+
1. Open Telegram and message [@BotFather](https://t.me/BotFather)
|
|
210
|
+
2. Send `/newbot` and follow prompts
|
|
211
|
+
3. Copy the bot token
|
|
212
|
+
|
|
213
|
+
### 4. Get Your Chat ID
|
|
214
|
+
|
|
215
|
+
1. Start a chat with your new bot
|
|
216
|
+
2. Send any message to it
|
|
217
|
+
3. Visit: `https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates`
|
|
218
|
+
4. Find `"chat":{"id": YOUR_CHAT_ID}` in the response
|
|
219
|
+
|
|
220
|
+
### 5. Update Settings
|
|
221
|
+
|
|
222
|
+
Replace `YOUR_BOT_TOKEN` and `YOUR_CHAT_ID` in `~/.claude/settings.json`
|
|
223
|
+
|
|
224
|
+
### 6. Restart Claude Code
|
|
225
|
+
|
|
226
|
+
## Environment Variables
|
|
227
|
+
|
|
228
|
+
| Variable | Description | Default |
|
|
229
|
+
|----------|-------------|---------|
|
|
230
|
+
| `TELEGRAM_BOT_TOKEN` | Bot token from @BotFather | Required |
|
|
231
|
+
| `TELEGRAM_CHAT_ID` | Your Telegram chat ID | Required |
|
|
232
|
+
| `SESSION_NAME` | Session identifier (for multi-instance) | "default" |
|
|
233
|
+
| `SESSION_PORT` | Preferred HTTP port (auto-finds if busy) | 3333 |
|
|
234
|
+
| `CHAT_RESPONSE_TIMEOUT_MS` | Timeout for message responses | 600000 (10 min) |
|
|
235
|
+
| `PERMISSION_TIMEOUT_MS` | Timeout for permission decisions | 600000 (10 min) |
|
|
236
|
+
|
|
237
|
+
## How It Works
|
|
238
|
+
|
|
239
|
+
```
|
|
240
|
+
Claude Code Hook Scripts telegram-claude-mcp
|
|
241
|
+
| | |
|
|
242
|
+
|-- Permission needed -------->| |
|
|
243
|
+
| |-- POST /permission --------->|
|
|
244
|
+
| | |-- Send to Telegram
|
|
245
|
+
| | |<- User clicks Allow
|
|
246
|
+
| |<-------- {allow} ------------|
|
|
247
|
+
|<-------- Allow --------------| |
|
|
248
|
+
| | |
|
|
249
|
+
|-- Work complete, stops ----->| |
|
|
250
|
+
| |-- POST /stop --------------->|
|
|
251
|
+
| | |-- Send to Telegram
|
|
252
|
+
| | |<- User replies
|
|
253
|
+
| |<-- {block, "do X next"} -----|
|
|
254
|
+
|<-- Continue with "do X" -----| |
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
## Multiple Sessions
|
|
258
|
+
|
|
259
|
+
Run multiple Claude instances with different session names:
|
|
260
|
+
|
|
261
|
+
```json
|
|
262
|
+
{
|
|
263
|
+
"env": {
|
|
264
|
+
"SESSION_NAME": "project-a"
|
|
265
|
+
}
|
|
266
|
+
}
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
Messages are tagged with `[project-a]` so you know which instance sent them.
|
|
270
|
+
|
|
271
|
+
## Troubleshooting
|
|
272
|
+
|
|
273
|
+
**Buttons appear but don't work:**
|
|
274
|
+
- Check for stale MCP processes: `ps aux | grep telegram-claude`
|
|
275
|
+
- Kill old processes and restart Claude
|
|
276
|
+
|
|
277
|
+
**No messages in Telegram:**
|
|
278
|
+
- Verify bot token and chat ID are correct
|
|
279
|
+
- Ensure you've started a chat with your bot
|
|
280
|
+
- Check Claude's MCP server logs
|
|
281
|
+
|
|
282
|
+
**Permission hook not firing:**
|
|
283
|
+
- Verify hook scripts are executable: `ls -la ~/.claude/hooks/`
|
|
284
|
+
- Check Claude settings have hooks configured
|
|
285
|
+
|
|
286
|
+
## License
|
|
287
|
+
|
|
288
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "telegram-claude-mcp",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.5.0",
|
|
4
4
|
"description": "MCP server that lets Claude message you on Telegram with hooks support",
|
|
5
5
|
"author": "Geravant",
|
|
6
6
|
"license": "MIT",
|
|
@@ -27,7 +27,8 @@
|
|
|
27
27
|
"files": [
|
|
28
28
|
"src",
|
|
29
29
|
"bin",
|
|
30
|
-
"hooks"
|
|
30
|
+
"hooks",
|
|
31
|
+
"README.md"
|
|
31
32
|
],
|
|
32
33
|
"scripts": {
|
|
33
34
|
"start": "node --import tsx src/index.ts",
|
package/src/index.ts
CHANGED
package/src/providers/index.ts
CHANGED
|
@@ -25,6 +25,7 @@ export interface AppConfig {
|
|
|
25
25
|
|
|
26
26
|
// Chat settings
|
|
27
27
|
responseTimeoutMs: number;
|
|
28
|
+
permissionTimeoutMs: number;
|
|
28
29
|
}
|
|
29
30
|
|
|
30
31
|
export function loadAppConfig(): AppConfig {
|
|
@@ -48,7 +49,8 @@ export function loadAppConfig(): AppConfig {
|
|
|
48
49
|
sessionPort: parseInt(sessionPort, 10),
|
|
49
50
|
openrouterApiKey: process.env.OPENROUTER_API_KEY,
|
|
50
51
|
openrouterModel: process.env.OPENROUTER_MODEL || 'openai/gpt-oss-120b',
|
|
51
|
-
responseTimeoutMs: parseInt(process.env.CHAT_RESPONSE_TIMEOUT_MS || '
|
|
52
|
+
responseTimeoutMs: parseInt(process.env.CHAT_RESPONSE_TIMEOUT_MS || '600000', 10),
|
|
53
|
+
permissionTimeoutMs: parseInt(process.env.PERMISSION_TIMEOUT_MS || '600000', 10),
|
|
52
54
|
};
|
|
53
55
|
}
|
|
54
56
|
|
package/src/telegram.ts
CHANGED
|
@@ -70,8 +70,8 @@ export class TelegramManager {
|
|
|
70
70
|
|
|
71
71
|
constructor(config: TelegramConfig) {
|
|
72
72
|
this.config = {
|
|
73
|
-
responseTimeoutMs:
|
|
74
|
-
permissionTimeoutMs:
|
|
73
|
+
responseTimeoutMs: 600000, // 10 minutes default
|
|
74
|
+
permissionTimeoutMs: 600000, // 10 minutes for permissions
|
|
75
75
|
...config,
|
|
76
76
|
};
|
|
77
77
|
|