mirror of
https://github.com/anthropics/claude-plugins-official.git
synced 2026-03-19 11:13:08 +00:00
Add discord channel plugin
Discord messaging bridge for Claude Code. Runs a local MCP server that connects to Discord's Gateway via a user-created bot token. Built-in access control: inbound messages are gated by an allowlist (default: pairing mode), outbound sends are scoped to the same allowlist. Guild channels require opt-in and @mention. The /discord:access skill manages pairing, allowlists, and policy. Ships full source — server.ts runs locally via bun, started by the .mcp.json command.
This commit is contained in:
Kenneth Lien
109
external_plugins/discord/README.md
Normal file
109
external_plugins/discord/README.md
Normal file
@@ -0,0 +1,109 @@
|
||||
# Discord
|
||||
|
||||
Connect a Discord bot to your Claude Code with an MCP server.
|
||||
|
||||
When the bot receives a message, the MCP server forwards it to Claude and provides tools to reply, react, and edit messages.
|
||||
|
||||
|
||||
## Quick Setup
|
||||
> Default pairing flow for a single-user DM bot. See [ACCESS.md](./ACCESS.md) for groups and multi-user setups.
|
||||
|
||||
**1. Create a Discord application and bot.**
|
||||
|
||||
Go to the [Discord Developer Portal](https://discord.com/developers/applications) and click **New Application**. Give it a name.
|
||||
|
||||
Navigate to **Bot** in the sidebar. Give your bot a username.
|
||||
|
||||
Scroll down to **Privileged Gateway Intents** and enable **Message Content Intent** — without this the bot receives messages with empty content.
|
||||
|
||||
**2. Generate a bot token.**
|
||||
|
||||
Still on the **Bot** page, scroll up to **Token** and press **Reset Token**. Copy the token — it's only shown once. Hold onto it for step 5.
|
||||
|
||||
**3. Invite the bot to a server.**
|
||||
|
||||
Discord won't let you DM a bot unless you share a server with it.
|
||||
|
||||
Navigate to **OAuth2** → **URL Generator**. Select the `bot` scope. Under **Bot Permissions**, enable:
|
||||
|
||||
- View Channels
|
||||
- Send Messages
|
||||
- Send Messages in Threads
|
||||
- Read Message History
|
||||
- Attach Files
|
||||
- Add Reactions
|
||||
|
||||
Integration type: **Guild Install**. Copy the **Generated URL**, open it, and add the bot to any server you're in.
|
||||
|
||||
> For DM-only use you technically need zero permissions — but enabling them now saves a trip back when you want guild channels later.
|
||||
|
||||
**4. Install the plugin.**
|
||||
|
||||
These are Claude Code commands — run `claude` to start a session first.
|
||||
|
||||
Install the plugin:
|
||||
```
|
||||
/plugin install discord@claude-plugins-official
|
||||
/reload-plugins
|
||||
```
|
||||
|
||||
Check that `/discord:configure` tab-completes. If not, restart your session.
|
||||
|
||||
**5. Give the server the token.**
|
||||
|
||||
```
|
||||
/discord:configure MTIz...
|
||||
```
|
||||
|
||||
Writes `DISCORD_BOT_TOKEN=...` to `~/.claude/channels/discord/.env`. You can also write that file by hand, or set the variable in your shell environment — shell takes precedence.
|
||||
|
||||
**6. Relaunch with the channel flag.**
|
||||
|
||||
The server won't connect without this — exit your session and start a new one:
|
||||
|
||||
```sh
|
||||
claude --channels plugin:discord@claude-plugins-official
|
||||
```
|
||||
|
||||
**7. Pair.**
|
||||
|
||||
DM your bot on Discord — it replies with a pairing code. In your assistant session:
|
||||
|
||||
```
|
||||
/discord:access pair <code>
|
||||
```
|
||||
|
||||
Your next DM reaches the assistant.
|
||||
|
||||
**8. Lock it down.**
|
||||
|
||||
Pairing is for capturing IDs. Once you're in, switch to `allowlist` so strangers don't get pairing-code replies. Ask Claude to do it, or `/discord:access policy allowlist` directly.
|
||||
|
||||
## Access control
|
||||
|
||||
See **[ACCESS.md](./ACCESS.md)** for DM policies, guild channels, mention detection, delivery config, skill commands, and the `access.json` schema.
|
||||
|
||||
Quick reference: IDs are Discord **snowflakes** (numeric — enable Developer Mode, right-click → Copy ID). Default policy is `pairing`. Guild channels are opt-in per channel ID.
|
||||
|
||||
## Tools exposed to the assistant
|
||||
|
||||
| Tool | Purpose |
|
||||
| --- | --- |
|
||||
| `reply` | Send to a channel. Takes `chat_id` + `text`, optionally `reply_to` (message ID) for native threading and `files` (absolute paths) for attachments — max 10 files, 25MB each. Auto-chunks; files attach to the first chunk. Returns the sent message ID(s). |
|
||||
| `react` | Add an emoji reaction to any message by ID. Unicode emoji work directly; custom emoji need `<:name:id>` form. |
|
||||
| `edit_message` | Edit a message the bot previously sent. Useful for "working…" → result progress updates. Only works on the bot's own messages. |
|
||||
| `fetch_messages` | Pull recent history from a channel (oldest-first). Capped at 100 per call. Each line includes the message ID so the model can `reply_to` it; messages with attachments are marked `+Natt`. Discord's search API isn't exposed to bots, so this is the only lookback. |
|
||||
| `download_attachment` | Download all attachments from a specific message by ID to `~/.claude/channels/discord/inbox/`. Returns file paths + metadata. Use when `fetch_messages` shows a message has attachments. |
|
||||
|
||||
Inbound messages trigger a typing indicator automatically — Discord shows
|
||||
"botname is typing…" while the assistant works on a response.
|
||||
|
||||
## Attachments
|
||||
|
||||
Attachments are **not** auto-downloaded. The `<channel>` notification lists
|
||||
each attachment's name, type, and size — the assistant calls
|
||||
`download_attachment(chat_id, message_id)` when it actually wants the file.
|
||||
Downloads land in `~/.claude/channels/discord/inbox/`.
|
||||
|
||||
Same path for attachments on historical messages found via `fetch_messages`
|
||||
(messages with attachments are marked `+Natt`).
|
||||
Reference in New Issue
Block a user