Content
# 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
```bash
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
```bash
npx @tensakulabs/discord-mcp status
# ✅ Connected as: yourname#0
```
## Manual MCP config (if auto-config fails)
Add to `~/.claude/settings.json`:
```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`:
```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
```json
{
"author": "username",
"content": "message text",
"channel": "channel-id",
"guild": "guild-id",
"is_dm": false
}
```
## OpenClaw integration
Add to OpenClaw's MCP config:
```json
{
"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.
