halobot

Your AI agent needs a phone number. Discord is it.

An open-source MCP server that gives any AI agent a Discord communication channel. Agents ask questions, wait for your reply, and keep working -- from your phone, desktop, wherever.

Human-Agent Loop Over Bot

Documentation . Quickstart . GitHub

The problem

Your agent is three hours into a refactoring task. It hits an ambiguous requirement. It guesses. It picks the wrong interpretation. It builds 400 lines on a bad assumption. You come back, see the mess, and start over.

Claude Code has dispatch. Cursor has its own notification system. Every AI tool reinvents "talk to the human."

halobot is the MCP answer: one Discord server, any agent, zero vendor lock-in.

Related MCP server: Brainstorm

Quick start

# Install globally
npm install -g @anthony-maio/halobot

# Interactive setup -- walks you through everything
halobot setup

That's it. The setup wizard links you to the Discord Developer Portal, generates the invite URL, collects your IDs, validates everything, and optionally configures Claude Code automatically.

# Check your setup
halobot doctor

# Check setup and send a test message
halobot doctor --test

How it works

+--------------+  STDIO/MCP  +------------------+  Discord API  +--------------+
|  Any Agent   |<------------>|     halobot      |<------------->|   Discord    |
| (Claude Code,|             |   MCP Server     | create thread |   Server     |
|  Cursor,     |  11 MCP     |                  | post message  |              |
|  Codex,      |  tools      |   Discord Bot    | wait for reply|   You        |
|  custom)     |             |                  |               |              |
+--------------+              +------------------+               +--------------+

1. Agent calls send_and_wait -- bot creates a Discord thread, pings you

2. You reply in the thread (phone, desktop, wherever)

3. Agent gets your response and keeps working

4. Long messages auto-chunk across Discord's 2000-char limit

MCP tools

High-level -- Thread conversations

Low-level -- Raw Discord access

Use cases

Decision points -- Agent hits an ambiguous requirement, asks which approach. You reply "option 2" from your phone.

Approval gates -- Agent reaches a deploy step, waits for your explicit "go" before continuing. No more 3 AM deploys.

Progress updates -- Agent posts status to the thread as it works. You check in when convenient.

Multi-agent coordination -- Multiple agents, each with their own thread, all reaching the same human. You're the hub.

Collaborative debugging -- Agent posts what it tried, asks for your intuition, tries again. Async pair programming.

Configuration

Claude Code (CLI)

claude mcp add halobot \
  -e DISCORD_BOT_TOKEN=your-token \
  -e DISCORD_CHANNEL_ID=your-channel-id \
  -e DISCORD_ALLOWED_USERS=your-user-id \
  -- halobot

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "halobot": {
      "command": "halobot",
      "env": {
        "DISCORD_BOT_TOKEN": "your-token",
        "DISCORD_CHANNEL_ID": "your-channel-id",
        "DISCORD_ALLOWED_USERS": "your-user-id"
      }
    }
  }
}

Any MCP client

halobot speaks standard MCP over STDIO. If your client supports MCP, it supports halobot.

Finding IDs: Enable Developer Mode in Discord settings -> right-click channel/user -> Copy ID.

Security

• Whitelist enforcement. Thread-based tools only respond to users in DISCORD_ALLOWED_USERS.

• Thread isolation. Each agent conversation gets its own thread. No cross-talk.

• No inbound commands. The bot doesn't accept arbitrary commands from Discord.

• Low-level tools are unrestricted -- they access any channel the bot can see. Use thread-based tools for controlled flows.

Development

# Run tests (no live Discord connection required)
npm test

# Dev mode with hot-reload
npm run dev

# TypeScript watch
npx tsc --watch

Roadmap

• SSE transport for remote/multi-agent access

• File/image attachment support via threads

• Reaction-based quick responses

• Persistent conversation state across server restarts

• Rate limiting per agent

• Webhook mode for push-based replies (no polling)

License

ISC

halobot.making-minds.ai

Built by Anthony Maio