discord-mcp

Discord selfbot MCP server — read & send Discord messages from Claude Code or OpenClaw.

⚠️ Selfbot Warning: This uses your Discord user token, which violates Discord's ToS. Your account may be banned. Use at your own risk.

What it does

Exposes 6 Discord tools via MCP (Model Context Protocol):

| Tool | Description | |------|-------------| | discord_list_guilds | List all servers you're in | | discord_list_channels | List text channels in a server | | discord_get_messages | Fetch recent messages from a channel | | discord_get_dms | List your open DM conversations | | discord_send_message | Send a message (channel or DM) | | discord_get_unread | Get messages you haven't seen yet |

A background daemon maintains a persistent WebSocket to the Discord Gateway, ingesting messages into a local SQLite database so discord_get_unread works even while Claude isn't running.

Setup

1. Install & configure

npx @tensakulabs/discord-mcp setup

This will:

1. Show you how to extract your Discord token from the desktop app
2. Save it securely to your OS keychain (macOS: uses built-in security CLI — no native module required)
3. Start the background daemon via launchd (macOS) or systemd (Linux)
4. Auto-register the MCP server in Claude's config

2. Token extraction (step shown during setup)

Open Discord desktop app → Press Ctrl+Shift+I (or Cmd+Option+I on Mac) → Network tab → Send any message in Discord → filter requests by messages → click any request → Headers tab → find the Authorization header → copy its value.

3. Restart Claude

Restart Claude Code. You'll see Discord tools available.

Verify it's working

npx @tensakulabs/discord-mcp status
# ✅ Connected as: yourname#0

Manual MCP config (if auto-config fails)

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "discord": {
      "command": "npx",
      "args": ["-y", "@tensakulabs/discord-mcp"]
    }
  }
}

Usage with Claude

Once registered, Claude can use Discord tools directly:

"What did I miss in the #general channel of the Tensaku server?"
→ Claude calls discord_list_guilds, discord_list_channels, discord_get_unread

"Reply to Alex saying I'll be there at 5pm"
→ Claude calls discord_send_message with replyToMessageId

Hooks

Fire shell commands or HTTP webhooks when Discord events occur. Configure in ~/.config/discord-mcp/config.json:

{
  "hooks": {
    "on_mention": [
      {
        "type": "command",
        "enabled": true,
        "command": "osascript -e 'display notification \"{content}\" with title \"Mention from {author}\"'"
      }
    ],
    "on_everyone": [],
    "on_here": [],
    "on_message": []
  }
}

Hook types

| Hook | Fires when | |------|-----------| | on_mention | Someone directly @username mentions you | | on_everyone | Someone uses @everyone in a server you're in | | on_here | Someone uses @here in a server you're in | | on_message | Any non-bot message (use sparingly — fires a lot) |

Hook config fields

| Field | Values | Description | |-------|--------|-------------| | type | "command" | "http" | Shell command or HTTP POST | | enabled | true | false | Toggle without removing | | command | string | Shell command (type: command) | | url | string | Endpoint to POST to (type: http) |

Template variables

Available in command strings and HTTP POST body:

| Variable | Value | |----------|-------| | {author} | Username of message sender | | {content} | Message text | | {channel} | Channel ID | | {guild} | Guild/server ID (or "dm" for DMs) | | {is_dm} | true or false |

HTTP hook payload

{
  "author": "username",
  "content": "message text",
  "channel": "channel-id",
  "guild": "guild-id",
  "is_dm": false
}

OpenClaw integration

Add to OpenClaw's MCP config:

{
  "mcp": {
    "servers": [{
      "name": "discord",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@tensakulabs/discord-mcp"]
    }]
  }
}

Security

• Token stored in OS keychain (macOS: security CLI — no native module compilation needed; Linux: keytar; fallback: AES-256-CBC encrypted file)
• Token never written to config files or logs
• Local files at ~/.config/discord-mcp/: messages.db, config.json, token.enc (fallback only), daemon.log

Architecture

discord-mcp/
├── src/
│   ├── index.ts          MCP server entry — registers 6 tools
│   ├── cli.ts            setup + status commands
│   ├── daemon.ts         Discord Gateway WebSocket → SQLite ingestion + hooks
│   ├── auth.ts           keychain token storage (macOS security CLI / keytar / encrypted file)
│   ├── hooks.ts          hook runner — shell commands and HTTP webhooks
│   ├── config.ts         config loader (~/.config/discord-mcp/config.json)
│   ├── db.ts             SQLite schema + queries
│   ├── ratelimit.ts      429 backoff + Discord headers
│   ├── state.ts          per-channel last-seen state
│   ├── purge.ts          scheduled message retention cleanup
│   └── tools/
│       ├── list_guilds.ts
│       ├── list_channels.ts
│       ├── get_messages.ts
│       ├── get_dms.ts
│       ├── send_message.ts
│       └── get_unread.ts

All Discord API calls go through rateLimitedFetch — automatic backoff on 429.

The daemon runs as a launchd service (com.discord-mcp.daemon) on macOS, connecting to wss://gateway.discord.gg and storing all messages locally for fast unread queries.