使用说明

呼叫人类mcp

您的AI代理即将删除生产数据库。你想让它继续下去吗？

呼叫人类mcp 是一个MCP服务器，它为任何AI代理提供了一个暂停按钮——它可以在采取行动之前问你一个问题或请求你的批准，在你做出回应之前它不会继续。

Claude:  request_approval("Drop table users_backup — 2.1GB, irreversible")

Slack:   ⚠️  AI Agent requesting approval
         Action: Drop table users_backup — 2.1GB, irreversible
         [Approve]  [Deny]
                              ← you click Deny
Claude:  "Understood, skipping the deletion."

适用于Claude Desktop、Cursor、Windsurf和任何兼容MCP的代理。通过Slack、Telegram或macOS系统对话框发送通知。

两个工具：

工具	何时使用	返回
`ask_human(question, context?)`	需要只有人类才能提供的信息	`str` --人类的文本回复
`request_approval(action, details?)`	在采取任何不可逆转的行动之前	`{"approved": bool, "reason": str}`

工具调用块直到您做出响应（或超时到期）。

5分钟快速启动

选择与您的设置匹配的路径：

频道	最适合	经过测试
CLI（macOS对话框）	macOS，不需要帐户	✅ 已测试
Slack	团队，批准/拒绝按钮	✅ 已测试
电报	个人使用、电话通知	⚠️ 轻度测试

选项A:CLI（macOS对话框）

不需要Slack或Telegram帐户。通过本机系统对话框在macOS上与Claude Desktop配合使用。

1.克隆并安装：

git clone https://github.com/nishantmodak/call-a-human-mcp
cd call-a-human-mcp
uv sync

2.验证其是否有效：

CALL_HUMAN_CHANNEL=cli uv run call-a-human-mcp --check

预期产量：

Checking cli channel...
CLI channel: OK (no credentials needed)

3.添加到克劳德桌面 (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "call-a-human": {
      "command": "/Users/yourname/.local/bin/uv",
      "args": ["--directory", "/path/to/call-a-human-mcp", "run", "call-a-human-mcp"],
      "env": {
        "CALL_HUMAN_CHANNEL": "cli"
      }
    }
  }
}

使用完整路径 uv，不仅 uv.Claude Desktop使用无法找到的受限PATH启动 uv 在 ~/.local/bin.快跑 which uv 以获得完整的路径。

4.重新启动克劳德桌面 （完全退出--Cmd+Q--然后重新打开）。

您将看到：

当克劳德来电时 ask_human，将出现一个本机macOS对话框：

┌─────────────────────────────────────────────────────┐
│  Claude is asking:                                  │
│  Which database environment should I target?        │
│                                                     │
│  [  Reply here...                                 ] │
│                              [Cancel]  [OK]         │
└─────────────────────────────────────────────────────┘

当克劳德来电时 request_approval，将出现一个具有“批准/拒绝”选项的对话框。克劳德会一直屏蔽，直到你回应。

是Linux/Windows还是CI？ 没有终端，就不存在交互式回退。请改用Telegram或Slack。

选项B：电报

⚠️ 未进行广泛测试。 实现遵循Telegram Bot API规范和基本流程，但可能存在边缘情况。欢迎反馈。

最适合个人使用——即时电话通知，按钮在Telegram应用程序中工作。

1.创建一个机器人：

消息 @植物学家 → /newbot → 按照提示操作→ 复制令牌

2.查找您的聊天ID：

向您的新机器人发送任何消息，然后运行：

curl "https://api.telegram.org/bot<TOKEN>/getUpdates" | python3 -m json.tool | grep '"id"' | head -1

该号码是您的聊天ID（对于群组为负数，例如。 -100123456789).

3.验证凭据：

CALL_HUMAN_CHANNEL=telegram \
TELEGRAM_BOT_TOKEN=<token> \
TELEGRAM_CHAT_ID=<chat_id> \
uv run call-a-human-mcp --check

预期产量：

Checking telegram channel...
  Bot token: OK (bot: @your_bot_username)
  Test message: OK (chat_id: -100123456789)

Telegram check passed. call-a-human-mcp is ready to use.

测试消息也会出现在您的Telegram聊天中。如果没有，请重新检查令牌和聊天ID。

4.添加到克劳德桌面：

{
  "mcpServers": {
    "call-a-human": {
      "command": "/Users/yourname/.local/bin/uv",
      "args": ["--directory", "/path/to/call-a-human-mcp", "run", "call-a-human-mcp"],
      "env": {
        "CALL_HUMAN_CHANNEL": "telegram",
        "TELEGRAM_BOT_TOKEN": "123456:ABC-your-token",
        "TELEGRAM_CHAT_ID": "-100123456789"
      }
    }
  }
}

5.重新启动克劳德桌面 （Cmd+Q→ 重新开放）。

您将看到：

当克劳德来电时 ask_human，您的Telegram聊天中会出现一条消息：

🤔 Claude is asking:
Which database environment should I target?

Context: Running migration job started at 14:32.

Reply to this message with your answer.

直接回复消息。克劳德收到你的回复并继续。

当克劳德来电时 request_approval，您将获得批准/拒绝按钮：

⚠️ Approval requested:
Deploy api-service v2.4.1 to production

Details: Replaces v2.3.8. 12 pods will restart.

[ ✅ Approve ]  [ ❌ Deny ]

点击按钮——克劳德立即收到结果。

选项C：松弛

最适合团队——批准/拒绝按钮，消息保留在团队的频道中。

完全权限参考： docs/slack-permissions.md

1.创建Slack应用程序：

首选 api.slack.com/apps → 创建新应用程序 → 从头开始
命名（例如。 call-a-human)并选择您的工作空间→ 创建应用程序

启用套接字模式：

侧边栏→ 插座模式 → 开启
生成具有作用域的应用级令牌 connections:write → 复制为 SLACK_APP_TOKEN (xapp-…)

添加机器人作用域：

侧边栏→ OAuth和权限 → Bot令牌范围 → Add: chat:write, channels:history （添加 groups:history 私人频道）

启用事件：

侧边栏→ 事件订阅 → 开启→ 订阅机器人事件 → Add message.channels （和/或 message.groups)

启用交互性：

侧边栏→ 交互性和快捷方式 → 开启→ Save

安装并获取令牌：

侧边栏→ 安装应用程序 → 安装到工作区 → Allow
复制 Bot用户OAuth令牌 作为 SLACK_BOT_TOKEN (xoxb-…)

查找您的频道ID:

在Slack中右键单击频道→ 复制链接 → 最后一段是ID（例如。 C1234567890)
邀请机器人：类型 /invite @call-a-human 在通道中

2.验证凭据：

CALL_HUMAN_CHANNEL=slack \
SLACK_BOT_TOKEN=xoxb-... \
SLACK_APP_TOKEN=xapp-... \
SLACK_CHANNEL_ID=C... \
uv run call-a-human-mcp --check

预期产量：

Checking slack channel...
  Bot token: OK (bot: @call-a-human, workspace: YourWorkspace)
  App token: OK (format looks correct)
  Test message: OK (channel: C1234567890, ts: 1234567890.123456)
  Socket Mode: OK (WebSocket connection established)

Slack check passed. call-a-human-mcp is ready to use.

所有四项检查都必须通过。如果Socket模式失败，请确保在您的Slack应用程序中启用了该模式，并且应用程序令牌正确。

3.添加到克劳德桌面：

{
  "mcpServers": {
    "call-a-human": {
      "command": "/Users/yourname/.local/bin/uv",
      "args": ["--directory", "/path/to/call-a-human-mcp", "run", "call-a-human-mcp"],
      "env": {
        "CALL_HUMAN_CHANNEL": "slack",
        "SLACK_BOT_TOKEN": "xoxb-your-bot-token",
        "SLACK_APP_TOKEN": "xapp-your-app-token",
        "SLACK_CHANNEL_ID": "C1234567890"
      }
    }
  }
}

4.重新启动克劳德桌面 （Cmd+Q→ 重新开放）。

您将看到：

当克劳德来电时 ask_human，Slack频道中会出现一条消息：

🤔 Claude is asking:
Which database environment should I target?

Context: Running migration job started at 14:32.
Reply in this thread ↓

在帖子中回复——克劳德收到你的短信回复并继续。

当克劳德来电时 request_approval，您将获得交互式按钮：

⚠️ Approval requested
Action: Deploy api-service v2.4.1 to production
Details: Replaces v2.3.8. 12 pods will restart.

[✅ Approve]  [❌ Deny]

点击按钮——Claude会立即收到结果，消息会更新以显示您的决定。

其他MCP客户端

光标

添加 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "call-a-human": {
      "command": "uv",
      "args": ["--directory", "/path/to/call-a-human-mcp", "run", "call-a-human-mcp"],
      "env": {
        "CALL_HUMAN_CHANNEL": "telegram",
        "TELEGRAM_BOT_TOKEN": "...",
        "TELEGRAM_CHAT_ID": "..."
      }
    }
  }
}

或者连接到正在运行的SSE服务器：

{
  "mcpServers": {
    "call-a-human": {
      "url": "http://localhost:8000/sse"
    }
  }
}

帆板运动

添加 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "call-a-human": {
      "serverUrl": "http://localhost:8000/sse"
    }
  }
}

首先启动SSE服务器：

CALL_HUMAN_CHANNEL=slack ... call-a-human-mcp --transport sse --host 0.0.0.0 --port 8000

作为持久性SSE服务器运行

安全说明： SSE传输没有内置身份验证。使用反向代理（nginx、Caddy）或防火墙规则保护它——任何可以访问该端口的人都可以向您的Slack/Telegram频道发送消息。

对于通过HTTP连接的自托管部署或客户端：

export CALL_HUMAN_CHANNEL=slack
export SLACK_BOT_TOKEN=xoxb-...
export SLACK_APP_TOKEN=xapp-...
export SLACK_CHANNEL_ID=C...

call-a-human-mcp --transport sse --host 0.0.0.0 --port 8000

或者使用Docker：

cp .env.example .env   # fill in your credentials
docker compose up -d

审计日志将写入 ./logs/audit.jsonl 在主机上。

让Claude自动调用这些工具

MCP服务器已经告诉Claude何时使用这些工具，但最可靠的方法是让Claude调用它们 主动地 --无需您明确要求，即可在您的AI客户端中添加自定义系统提示。

关键原则（从生产使用中学到）： 告诉克劳德直接调用这些工具，而不是问你是否要调用它们。 批准发生在Slack/Telegram中。克劳德的工作就是触发它。

克劳德桌面版

首选 设置→ 自定义指令 并添加：

You have access to request_approval and ask_human tools via the call-a-human MCP server.

Call request_approval BEFORE any irreversible action: deleting files, sending
messages, making purchases, modifying production systems, running destructive
commands. Do NOT ask "should I proceed?" — just call the tool and wait.
Only continue if you receive {"approved": true}.

Call ask_human when you are unsure about preferences, file paths, credentials,
or any ambiguous decision. Never guess — ask.

这使得所有对话中的行为都是一致的，不需要每次都提醒克劳德。

光标/风帆

添加一个 .cursorrules 文件（游标）或与您的项目等效的文件：

Before any irreversible action, call the request_approval MCP tool directly —
do not ask the user whether to call it. Wait for {"approved": true} before proceeding.
When unsure about preferences or credentials, call ask_human instead of guessing.

交互式尝试工具（无需人工智能代理）

使用MCP检查器直接调用工具：

CALL_HUMAN_CHANNEL=cli uv run mcp dev src/call_a_human_mcp/server.py

浏览器UI允许您调用 ask_human 和 request_approval 手动并检查响应。

所有配置选项

变量	必填	默认	描述
`CALL_HUMAN_CHANNEL`	是	--	`cli`, `slack`，或 `telegram`
`CALL_HUMAN_TIMEOUT`	没有	`300`	自动拒绝前等待的秒数
`CALL_HUMAN_AUDIT_LOG`	否	--	JSONL审核日志文件的路径
`SLACK_BOT_TOKEN`	仅限Slack	--	Bot OAuth令牌(`xoxb-…`)
`SLACK_APP_TOKEN`	仅限Slack	--	套接字模式应用程序令牌(`xapp-…`)
`SLACK_CHANNEL_ID`	仅限Slack	--	发布到的频道(`C…`)
`TELEGRAM_BOT_TOKEN`	仅限电报	--	来自@BotFather的机器人令牌
`TELEGRAM_CHAT_ID`	仅限电报	--	要发布到的聊天/群组ID

复制 .env.example 到 .env 并填写你的价值观。

审计日志

集 CALL_HUMAN_AUDIT_LOG 要启用仅追加JSONL日志记录：

CALL_HUMAN_AUDIT_LOG=./logs/audit.jsonl call-a-human-mcp

每一行都是一个JSON对象：

// ask_human
{"timestamp":"2024-03-01T12:00:00.123Z","request_id":"abc123","tool":"ask_human","question":"Which env?","context":"","timed_out":false,"duration_ms":4210}

// request_approval
{"timestamp":"2024-03-01T12:05:00.456Z","request_id":"def456","tool":"request_approval","action":"delete db","details":"","approved":true,"reason":"alice","timed_out":false,"duration_ms":8700}

尾巴和漂亮的印花现场直播：

tail -f logs/audit.jsonl | python3 -m json.tool

运作原理

AI agent (Claude)              call-a-human-mcp           Human (Slack/Telegram/macOS)
─────────────────              ────────────────           ────────────────────────────
request_approval(             block on                   sees message with
  "delete database")   ──►    threading.Event    ──►     Approve / Deny buttons
                                                          │
                                                          │ clicks Approve
                                                          ▼
{"approved": true,    ◄──    event.set()         ◄──    button/dialog handler fires
 "reason": "alice"}

MCP工具处理程序在 threading.Event。后台守护进程线程（Slack Socket模式、Telegram长轮询或macOS对话子进程）会触发 event.set() 当人类做出反应时。

发展

git clone https://github.com/nishantmodak/call-a-human-mcp
cd call-a-human-mcp
uv sync --extra dev

uv run --extra dev pytest -v
uv run --extra dev ruff check src tests

通过新渠道进行扩展

创建 src/call_a_human_mcp/channels/sms.py 子类化 Channel
实施 start(), ask()，以及 request_approval()
添加 "sms" 到 config.py 使用所需的环境变量进行验证
在中添加工厂分支 server.pys create_server()
添加 --check 支持 __main__.pys _run_check()

无需更改MCP工具定义。

故障排除

看 docs/故障排除.md 常见问题的解决方案：

Claude Desktop“生成进程失败”→ 使用完整路径 uv
未收到松弛线程回复→ 专用频道需要额外权限
message.groups 未显示在Slack事件列表中→ add groups:read 范围优先
克劳德不会自动调用工具→ 添加自定义系统提示

社区

问题、想法，或者只是想分享你是如何使用它的？加入Discord.

许可证

Apache 2.0——请参阅许可证了解详情。

使用说明

呼叫人类mcp

5分钟快速启动

选项A:CLI（macOS对话框）

选项B：电报

选项C：松弛

其他MCP客户端

光标

帆板运动

作为持久性SSE服务器运行

让Claude自动调用这些工具

克劳德桌面版

光标/风帆

交互式尝试工具（无需人工智能代理）

所有配置选项

审计日志

运作原理

发展

通过新渠道进行扩展

故障排除

社区

许可证

相关 MCP

Windows命令行服务器

PostgreSQL管理服务器

Supabase MCP 服务器

Supabase数据库管理服务器

浏览器控制MCP

进程管理MCP服务器