Raise Hand

This MCP Server integrates with a Discord bot to allow AI agents to send a distress call or "raise their hand" when they encounter an issue they cannot solve, or when they need human input. The agent will pause, post a message to Discord, and wait for a human to reply or react. Once the human replies to the message or reacts with a valid emoji (👍, 👎, ✅, ❌) in Discord, the agent captures the response and resumes its work.

It also exposes tiny_llm_task, which offloads small, cheap tasks to a local llama-cpp-scripts chat model instead of the main model. On startup, this server runs that project's npm run models to list available models in the tool's description; the npm run chat server itself is started on demand on the first tiny_llm_task call, and stopped after LLAMA_IDLE_TIMEOUT seconds of inactivity.

Setup Instructions

1. Create a Discord Bot

1. Go to the Discord Developer Portal.
2. Click New Application and give it a name.
3. Go to the Bot tab and click Add Bot (if not already added).
4. Under Privileged Gateway Intents, turn on Message Content Intent (so it can read human replies).
5. Copy the Token (you will need this later). Do not share this token!

2. Invite the Bot to your Server

1. In the Developer Portal, go to OAuth2 -> URL Generator.
2. Select the bot scope.
3. Select the following Bot Permissions: Read Messages/View Channels, Send Messages, Read Message History, and Add Reactions.
4. Copy the generated URL and paste it into your browser to invite the bot to your desired Discord server.

3. Get the Channel ID

1. In Discord, go to User Settings -> Advanced and turn on Developer Mode.
2. Right-click the channel where you want the bot to post messages and click Copy Channel ID.

4. Configure the Environment

Create a .env file in the root of this project and add your token and channel ID:

DISCORD_BOT_TOKEN=your_bot_token_here
DISCORD_CHANNEL_ID=your_channel_id_here

# Optional: enables the tiny_llm_task tool
# https://github.com/jjjpanda/llama-cpp-scripts
LLAMA_SCRIPTS_PATH=/absolute/path/to/llama-cpp-scripts
LLAMA_CHAT_PORT=8080
LLAMA_IDLE_TIMEOUT=300

5. Running the MCP Server

Install the dependencies:

python -m venv .venv
# On Windows
.venv\Scripts\activate
# On Linux/macOS
source .venv/bin/activate
pip install -r requirements.txt

Option A: Testing (MCP Inspector)

Run the MCP Inspector to test the server interactively in your browser:

npx @modelcontextprotocol/inspector .venv/Scripts/python server.py

Option B: Regular Running (For MCP Clients)

To use this server with an MCP client (like Claude for Desktop, Cursor, or your custom AI agent workflows), configure the client to run the Python script directly. The server automatically communicates via standard input/output (stdio).

For example, in claude_desktop_config.json, you would add:

{
  "mcpServers": {
    "raise-hand-mcp": {
      "command": "/absolute/path/to/raise-hand-mcp/.venv/Scripts/python",
      "args": [
        "/absolute/path/to/raise-hand-mcp/server.py"
      ],
      "env": {
        "DISCORD_BOT_TOKEN": "your_bot_token_here",
        "DISCORD_CHANNEL_ID": "your_channel_id_here"
      }
    }
  }
}

(Make sure to use the absolute paths for the python executable inside the .venv directory and for server.py.)

Option C: Claude Code

To add this server to Claude Code, you can use the claude mcp add command. Since the server automatically loads your .env file, you don't need to pass your tokens in the terminal. Just provide the absolute path to your virtual environment's Python executable and the server.py script:

claude mcp add raise-hand-mcp /absolute/path/to/raise-hand-mcp/.venv/Scripts/python /absolute/path/to/raise-hand-mcp/server.py