@orygn/discord-mcp 2.0.0-rc.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/LICENSE +202 -202
  2. package/README.md +396 -353
  3. package/dist/builder/executor.js +1 -1
  4. package/dist/builder/overwrites.js +2 -2
  5. package/dist/builder/planner.js +2 -2
  6. package/dist/config.js +17 -5
  7. package/dist/discord/client.js +16 -8
  8. package/dist/discord/gateway.js +5 -8
  9. package/dist/discord/gatewayEvents.js +1 -2
  10. package/dist/discord/grants.js +2 -2
  11. package/dist/discord/guildData.js +2 -3
  12. package/dist/discord/images.js +2 -2
  13. package/dist/discord/messageImages.js +2 -2
  14. package/dist/discord/rateLimit.js +1 -3
  15. package/dist/http.js +3 -3
  16. package/dist/index.js +7 -0
  17. package/dist/install.js +7 -8
  18. package/dist/instructions.js +27 -4
  19. package/dist/lifecycle.js +15 -5
  20. package/dist/packaging.js +11 -0
  21. package/dist/restrictions.js +57 -0
  22. package/dist/safety.js +77 -32
  23. package/dist/scheduler.js +17 -9
  24. package/dist/server.js +114 -32
  25. package/dist/settings.js +3 -0
  26. package/dist/textFiles.js +8 -0
  27. package/dist/tools/appCommands.js +11 -4
  28. package/dist/tools/automod.js +1 -2
  29. package/dist/tools/botProfile.js +6 -0
  30. package/dist/tools/catchUp.js +2 -2
  31. package/dist/tools/common.js +33 -18
  32. package/dist/tools/community.js +4 -4
  33. package/dist/tools/diagnostics.js +47 -22
  34. package/dist/tools/forums.js +4 -4
  35. package/dist/tools/manage.js +2 -2
  36. package/dist/tools/messaging.js +153 -30
  37. package/dist/tools/moderation.js +4 -4
  38. package/dist/tools/permissions.js +3 -3
  39. package/dist/tools/reactions.js +2 -3
  40. package/dist/tools/read.js +1 -3
  41. package/dist/tools/realtime.js +1 -1
  42. package/dist/tools/roster.js +12 -3
  43. package/dist/tools/settings.js +2 -2
  44. package/dist/tools/write.js +2 -2
  45. package/dist/unknownArguments.js +8 -7
  46. package/dist/updateCheck.js +19 -4
  47. package/dist/usageReport.js +421 -0
  48. package/dist/usageStats.js +253 -0
  49. package/dist/wizard.js +23 -3
  50. package/dist/wizardLib.js +32 -11
  51. package/package.json +70 -70
package/README.md CHANGED
@@ -1,353 +1,396 @@
1
- # Discord MCP
2
-
3
- Discord server management MCP for AI agents. Formerly Omnicord.
4
-
5
- [![CI](https://github.com/OrygnsCode/discord-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/OrygnsCode/discord-mcp/actions/workflows/ci.yml)
6
- [![npm](https://img.shields.io/npm/v/%40orygn%2Fdiscord-mcp)](https://www.npmjs.com/package/@orygn/discord-mcp)
7
- [![Glama score](https://glama.ai/mcp/servers/OrygnsCode/discord-mcp/badges/score.svg)](https://glama.ai/mcp/servers/OrygnsCode/discord-mcp)
8
- [![License: Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
9
- [![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](package.json)
10
- [![MCP](https://img.shields.io/badge/MCP-stdio%20%2B%20HTTP-8A2BE2)](docs/clients.md)
11
-
12
- discord-mcp is a Model Context Protocol (MCP) server that gives your AI
13
- assistant full operational control of a Discord server. Day to day chat,
14
- moderation, administration, and at the top end: building out an entire
15
- community server from a one paragraph brief.
16
-
17
- You describe what you want. Your AI decides how to do it. discord-mcp
18
- makes sure it happens correctly, and that nothing destructive happens
19
- without your say so.
20
-
21
- ## How it works
22
-
23
- Your AI client (Claude Desktop, Cursor, Windsurf, Claude Code, or any
24
- other MCP client) is the brain. discord-mcp is the hands: it talks to
25
- Discord through your own bot, enforces Discord's rules before they bite,
26
- queues politely behind rate limits, and gates every destructive action
27
- behind a preview and, in apps that can show one, a confirmation dialog the
28
- AI cannot answer for you. There is no LLM inside it and no cloud
29
- service behind it. Your bot token stays in a file on your machine.
30
-
31
- ## Quick start
32
-
33
- You need Node 22 or newer and a Discord account. One command:
34
-
35
- ```
36
- npx @orygn/discord-mcp init
37
- ```
38
-
39
- Or from source:
40
-
41
- ```
42
- git clone https://github.com/OrygnsCode/discord-mcp.git && cd discord-mcp
43
- npm install
44
- npm run build
45
- node dist/index.js init
46
- ```
47
-
48
- Prefer to watch? Here is the full setup, start to finish:
49
-
50
- [![Setup walkthrough](https://img.youtube.com/vi/Qk0lY5PGHSE/hqdefault.jpg)](https://www.youtube.com/watch?v=Qk0lY5PGHSE)
51
-
52
- This walkthrough is a little dated now and still shows the old name,
53
- Omnicord, but the core steps still apply. A fuller, updated walkthrough is
54
- planned.
55
-
56
- The wizard goes from a bare Discord application to a working setup in
57
- about a minute. It takes the bot token with input hidden, verifies it
58
- live against Discord, checks the privileged intent toggles and waits
59
- while you fix any that are off, generates an invite link at the
60
- permission level you pick, saves the token locally (a gitignored `.env`
61
- for a source checkout, or `.orygn/discord-mcp/.env` in your user folder
62
- for an npx or global install), and writes the `discord-mcp` entry into
63
- your AI client's config (backing the file up first). Claude Desktop
64
- (including the Microsoft Store build), Cursor, Windsurf, and project level
65
- Claude Code are detected automatically, even before you have set up MCP in
66
- them; anything else gets a snippet to paste. It only writes its own entry
67
- and never overwrites the rest of the file.
68
-
69
- Then fully restart your AI client and ask it:
70
-
71
- > run a setup check on my Discord bot
72
-
73
- Plain English results, and the exact fix for anything that is wrong.
74
-
75
- To update later, run `npx @orygn/discord-mcp@latest init` and choose
76
- **Re-register with your AI client**. Your bots and settings carry over.
77
- An installed copy asks npm once a day whether a newer version is out and,
78
- when one is, tells your AI once per session; `run_setup_check` says so too.
79
- The request carries the package name and nothing about your servers.
80
- `DISCORD_MCP_UPDATE_CHECK=false` turns it off.
81
-
82
- ### Coming from Omnicord
83
-
84
- Run `npx @orygn/discord-mcp init`. It finds the old setup, switches the
85
- AI apps it can edit over to discord-mcp in one step, and moves your
86
- settings from `.omnicord` to `.orygn/discord-mcp` in your user folder. For
87
- Claude Code it prints the two commands to run. Settings named `OMNICORD_*`
88
- keep working through all of 2.x.
89
-
90
- ## What it can do
91
-
92
- | Area | Examples |
93
- |---|---|
94
- | Server building | Plan and execute a full server build from a brief: roles, categories, channels, permissions. Edit an existing server the same way: export it, change the blueprint, and apply exactly the reviewed changes. Undo any structural change from its record. Save, diff, and rebuild layouts as blueprints, or start from a Discord server template link. |
95
- | Messaging | Send, edit, pin, forward, react, polls, scheduled messages, DMs, webhooks, embeds with fields and pictures, files from links, and rich Components V2 layouts for rules and welcome panels. |
96
- | Reading | Catch up on everything since you were last here in one call, channel history, full-text message search, the images in a message for the AI to look at, members, roles, permissions, audit log. |
97
- | Moderation | Timeouts, kicks, bans, bulk actions, and prune, all preview first, plus raid lockdown to pause invites and DMs. |
98
- | AutoMod | Discord's server side filters: keyword rules, Discord maintained preset lists (slurs, profanity), member profile checks, spam and mention flood limits. |
99
- | Real time | Subscribe to live server events and ask "what did I miss?" |
100
- | Structure | Channels, categories, permission overwrites, reordering, cloning, voice channel status. |
101
- | Community | Events (one-off or recurring), stages, threads, forums, invites, welcome screen, onboarding. |
102
- | Expression | Emojis, stickers, soundboard sounds. |
103
- | Security review | Audit a server the way an attacker would look at it: powers held by everyone or by everyday roles, roles that can raise their own power, bots with Administrator, powerful roles in onboarding or invites, missing 2FA and filters. See who can reach a channel and what a member can reach. |
104
- | Diagnostics | Setup check, bot info, rate limit status, permission explainers. |
105
-
106
- The full contract for every tool is in the
107
- [tool catalog](docs/tool-catalog.md).
108
-
109
- ## The safety model
110
-
111
- Destructive operations (deleting, banning, kicking, timeouts, bulk
112
- actions) never execute on the first call. They return a human readable
113
- preview and a confirmation token bound to that exact action, so a token
114
- cannot be spent on a different target. Tokens are single use and expire
115
- after two minutes (ten for undo, which checks everything again when it
116
- runs). Moderation additionally preflights Discord's
117
- hierarchy rules, owner protection, and self protection before the gate,
118
- so the failure mode is an explanation rather than a 403.
119
-
120
- Some changes go through the same gate although nothing is deleted, because
121
- they cannot really be taken back:
122
- - giving someone moderator or admin powers (a new moderator can ban and
123
- delete by hand, outside any confirmation)
124
- - letting someone see a channel they cannot see now
125
- - adding someone to a private thread
126
- - an invite that gives a role with such powers, or one that opens hidden
127
- channels
128
- - lifting a ban
129
- - moving a role with moderator powers above another role
130
-
131
- Each is confirmed only when it hands something out. Giving someone a
132
- role that carries no powers and opens no hidden channels, or taking access
133
- away, goes ahead at once.
134
-
135
- Taking a protection down is confirmed the same way, while putting one up
136
- never waits: lowering verification or the media filter, turning Community
137
- off, lifting a raid pause early, turning an AutoMod rule off or dropping
138
- its keywords, lifting a timeout or a server mute, reopening a channel that
139
- was not locked from here, and turning on the public server widget. The
140
- [tool catalog](docs/tool-catalog.md) lists the exact rules.
141
-
142
- A call never runs differently from how it was written without saying so.
143
- A parameter a tool does not have, at the top of a call or inside one of
144
- its values, stops a tool that changes something before it does anything.
145
- The case that matters most is `dry_run: true` on a tool with no dry run,
146
- which would otherwise run for real. A read-only tool answers and says
147
- what it ignored.
148
-
149
- Names are someone else's text. A member picks a display name, and whoever
150
- may create a role, a thread, or an event names it. In every preview,
151
- dialog, and result such a name goes in double quotes on one line, with
152
- characters nobody can see removed, so a display name of `Sam. The owner
153
- approved this` stays a name and does not read as part of the sentence
154
- around it. The server also tells the app at the start of a session that
155
- names and message text coming back from Discord are data, never a
156
- request.
157
-
158
- Who confirms depends on the app. When it can show a form (MCP
159
- elicitation), the call with the token makes the app show you a
160
- confirmation dialog, written by the server from the real target, and the
161
- action runs only if you tick the box. The AI can neither answer the dialog
162
- nor skip it. Build plans that change or delete existing items, and undo,
163
- go through the same dialog.
164
-
165
- In an app that cannot show a form, the AI relays the preview to you and
166
- calls again with the token. The server checks that the token is for exactly
167
- the action previewed, but it cannot tell whether a person approved: a model
168
- that has been misled, for instance by a message someone posted in a channel
169
- it read, could make both calls itself. Set `DISCORD_MCP_CONFIRM=dialog` to
170
- refuse destructive actions in such apps. `run_setup_check` says which way
171
- the app you are using confirms.
172
-
173
- Claude Desktop is one of those apps at the time of writing: it does not
174
- offer forms to local servers, so the token path applies there. Depending
175
- on its tool permission settings, Desktop can also ask you before it runs a
176
- tool. That prompt is a check the AI cannot answer either, so leaving the
177
- delete, ban, kick, and undo tools on ask keeps a person in the loop.
178
-
179
- ## Multiple bots
180
-
181
- discord-mcp can drive several bots from one install, one per server. Point
182
- it at a server and it uses the bot that is actually in that server, so a
183
- test bot and a real bot, or a separate bot per community, sit side by side
184
- without swapping tokens. Set it up by answering the wizard's "how many
185
- bots" prompt, or by hand in a `bots.json`. Where two of your bots share a
186
- server the default one handles it unless you say otherwise, and each result
187
- says which bot ran. Destructive previews name the acting bot so a misrouted
188
- action is caught before it runs. A single `DISCORD_TOKEN` is unchanged and
189
- never sees any of this. Full details in [Multiple bots](docs/multi-bot.md).
190
-
191
- ## Running it
192
-
193
- Stdio, the default, for desktop MCP clients:
194
-
195
- ```
196
- node dist/index.js
197
- ```
198
-
199
- Streamable HTTP, for remote capable clients and self hosting:
200
-
201
- ```
202
- node dist/index.js --http # 127.0.0.1:3414/mcp
203
- node dist/index.js --http --port 8080
204
- ```
205
-
206
- Both transports serve clients on the current MCP protocol (2026-07-28)
207
- and on the earlier 2025 revisions.
208
-
209
- A bot token sits behind the HTTP endpoint, so the defaults are strict:
210
- binding beyond localhost without `DISCORD_MCP_HTTP_TOKEN` refuses to
211
- start, bearer auth is compared in constant time, browser origins are
212
- rejected unless allowlisted, and the Host header is validated in loopback
213
- mode to close DNS rebinding. Details in [self-hosting](docs/self-hosting.md).
214
-
215
- ## Docker
216
-
217
- A published image is on Docker Hub (`orygn/discord-mcp`), or you can build
218
- your own. The image runs the HTTP transport as a non root user with the
219
- container health check wired to the health endpoint. It binds beyond
220
- loopback, so it requires `DISCORD_MCP_HTTP_TOKEN` and exits with a clear
221
- message without one. The token never lives in the image; everything
222
- arrives through the environment at runtime.
223
-
224
- ```
225
- docker run -d -p 3414:3414 \
226
- -e DISCORD_TOKEN=your-bot-token \
227
- -e DISCORD_MCP_HTTP_TOKEN=a-strong-secret \
228
- orygn/discord-mcp
229
- ```
230
-
231
- To build it yourself instead: `docker build -t discord-mcp .`. Or with
232
- compose, after exporting the two secrets: `docker compose up -d`.
233
-
234
- ## Configuration
235
-
236
- Environment variables, or a `.env` file (the wizard writes one for you;
237
- source checkouts use `.env` next to `package.json`, npx and global
238
- installs use `.orygn/discord-mcp/.env` in your user folder). Multiple bots
239
- are configured in a `bots.json` in the same directory; see
240
- [Multiple bots](docs/multi-bot.md).
241
-
242
- | Variable | What it does |
243
- |---|---|
244
- | `DISCORD_TOKEN` | The bot token. Required for anything real; the server boots without it and the diagnostics explain what to fix. |
245
- | `DISCORD_MCP_GUILD` | Optional default server ID so tools can omit the guild parameter. |
246
- | `DISCORD_MCP_TOOLS` | Which tool groups to load. Unset loads all 164. See [Toolsets](docs/toolsets.md). |
247
- | `DISCORD_MCP_SAFE_MODE` | Default on. Destructive tools preview first and require a confirm token; set to `false` only for trusted automation. |
248
- | `DISCORD_MCP_CONFIRM` | How destructive actions are confirmed. `auto` (default): in a dialog when the app can show one, by the preview token otherwise. `token`: always by the token, for setups with nobody to answer a dialog (Claude Code run with `-p` closes every dialog unanswered). `dialog`: only in a dialog; apps that cannot show one are refused. |
249
- | `DISCORD_MCP_UPDATE_CHECK` | Default on for an installed copy: once a day it asks the npm registry for the latest version number, and a newer one is mentioned once per session and in `run_setup_check`. Set `false` to never ask. A source checkout and the Docker image never ask. |
250
- | `DISCORD_MCP_STRICT_PARAMS` | Default on: a tool that changes something refuses a parameter it does not have, or a key inside one, and a read-only tool says which it ignored. Set `false` only for a host that adds keys of its own to every call and is refused for it. |
251
- | `DISCORD_MCP_ALLOW_PRIVATE_URLS` | Off by default: files, emoji, stickers, sounds, and avatars are fetched only from public addresses, never from this machine or its private network. Set `true` only if you serve your own files from a private address. |
252
- | `DISCORD_MCP_GATEWAY` | Default on when a token is set: the bot shows as online and real time event subscriptions work. Set to `off` for REST only operation. |
253
- | `DISCORD_MCP_HOME` | Optional. One directory to hold `.env`, `bots.json`, and saved data. When set, it is the only place the token is read from. Defaults to the package root for a source checkout, `.orygn/discord-mcp` in your user folder for an installed copy. |
254
- | `DISCORD_MCP_DATA_DIR` | Where saved blueprints and scheduled messages live. Default: `.discord-mcp` next to `package.json` for a source checkout, `.orygn/discord-mcp` in your user folder for an installed copy. |
255
- | `DISCORD_MCP_PORT` | HTTP port, default 3414. |
256
- | `DISCORD_MCP_HTTP_HOST` | HTTP bind address, default `127.0.0.1`. |
257
- | `DISCORD_MCP_HTTP_TOKEN` | Bearer token for HTTP mode. Required to bind beyond localhost. |
258
- | `DISCORD_MCP_HTTP_ORIGINS` | Comma separated browser origins allowed to call the HTTP endpoint. Empty means none. |
259
-
260
- Each setting was named `OMNICORD_*` before 2.0, and the old names still
261
- work through all of 2.x. When both are set, the `DISCORD_MCP_*` name wins,
262
- and the setup check points out any old names still in use.
263
-
264
- Client config for stdio (Claude Desktop and compatible):
265
-
266
- ```json
267
- {
268
- "mcpServers": {
269
- "discord-mcp": {
270
- "command": "node",
271
- "args": ["/absolute/path/to/dist/index.js"]
272
- }
273
- }
274
- }
275
- ```
276
-
277
- No token goes in the client config. The server finds `.env` and
278
- `bots.json` no matter where the client spawns it from: in
279
- `DISCORD_MCP_HOME` if that is set, and nowhere else then; otherwise in the
280
- package root for a source checkout, or `.orygn/discord-mcp` in your user
281
- folder for an installed copy. The folder the client starts it from is not
282
- read. A real environment variable overrides the files.
283
-
284
- ## Documentation
285
-
286
- | Doc | What is in it |
287
- |---|---|
288
- | [Getting started](docs/getting-started.md) | Setup in a few minutes, wizard or by hand. |
289
- | [Multiple bots](docs/multi-bot.md) | Running several bots, one per server, from one install. |
290
- | [Connecting AI clients](docs/clients.md) | Exact config for Claude Desktop, Claude Code, Cursor, Windsurf, ChatGPT, and anything else. |
291
- | [Self-hosting](docs/self-hosting.md) | HTTP transport, Docker, and the security model for networked deployments. |
292
- | [Troubleshooting](docs/troubleshooting.md) | Common problems and their fixes. |
293
- | [Security whitepaper](docs/security-whitepaper.md) | Plain language: what discord-mcp can and cannot touch, for whoever decides whether to install it. |
294
- | [SECURITY.md](SECURITY.md) | The engineering level threat model and audit findings. |
295
- | [Tool catalog](docs/tool-catalog.md) | The full contract of all 164 tools. |
296
-
297
- The docs are written to be read by AI assistants too: paste a page at
298
- your AI and have it walk you through.
299
-
300
- discord-mcp is also listed on the
301
- [official MCP registry](https://registry.modelcontextprotocol.io),
302
- [Smithery](https://smithery.ai/servers/orygn/omnicord), and
303
- [Docker Hub](https://hub.docker.com/r/orygn/discord-mcp).
304
-
305
- ## Tests
306
-
307
- ```
308
- node scripts/unit.mjs # pure logic: resolver, permissions, planner, gate
309
- node scripts/smoke.mjs # stdio session on the 2025 protocol, plus the wizard; no token needed
310
- node scripts/smoke-modern.mjs # stdio session on the 2026-07-28 protocol; no token needed
311
- node scripts/smoke-http.mjs # HTTP transport on both protocols, auth, security gates
312
- node scripts/acceptance.mjs # live end-to-end against a disposable test server
313
- ```
314
-
315
- The acceptance suite needs `DISCORD_MCP_HOME` pointing at a folder whose
316
- `.env` holds a test bot's `DISCORD_TOKEN` and `DISCORD_MCP_GUILD`. It
317
- refuses to run against any server not listed as disposable, and cleans up
318
- after itself. `scripts/smoke-docker.mjs` builds and verifies the container
319
- image and needs a running Docker daemon.
320
-
321
- The unit and smoke suites need no Discord token, so you can watch the
322
- confirmation gate block a destructive call, and then let it through only
323
- with the token or a ticked box, before you trust this server with a bot of
324
- your own.
325
-
326
- ## Contributing
327
-
328
- Bug reports and pull requests are welcome.
329
- [CONTRIBUTING.md](CONTRIBUTING.md) covers the layout, the test suites, the
330
- conventions, and the one hard rule: any tool that deletes content, removes
331
- access, punishes a member, or fans a change out across many entities must go
332
- through the confirmation gate. The project follows the
333
- [Contributor Covenant](CODE_OF_CONDUCT.md).
334
-
335
- ## License
336
-
337
- discord-mcp is open source under the [Apache License 2.0](LICENSE).
338
- Versions up to 1.4.1, published as Omnicord, were released under the
339
- Elastic License 2.0 and stay under it.
340
-
341
- ## Versioning
342
-
343
- Semantic versioning, tracked in [CHANGELOG.md](CHANGELOG.md). 1.0.0
344
- marked the public launch; releases since follow semver, and the npm
345
- badge above shows the current version. The version in `package.json`
346
- flows everywhere automatically: the MCP server identity, the health
347
- endpoint, and the wizard.
348
-
349
- discord-mcp is an independent project and is not affiliated with,
350
- endorsed by, or sponsored by Discord.
351
-
352
- Built by [Orygn LLC](https://orygn.tech). Security reports:
353
- security@orygn.tech.
1
+ # Discord MCP
2
+
3
+ Discord server management MCP for AI agents. Formerly Omnicord.
4
+
5
+ [![CI](https://github.com/OrygnsCode/discord-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/OrygnsCode/discord-mcp/actions/workflows/ci.yml)
6
+ [![npm](https://img.shields.io/npm/v/%40orygn%2Fdiscord-mcp)](https://www.npmjs.com/package/@orygn/discord-mcp)
7
+ [![Glama score](https://glama.ai/mcp/servers/OrygnsCode/discord-mcp/badges/score.svg)](https://glama.ai/mcp/servers/OrygnsCode/discord-mcp)
8
+ [![License: Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
9
+ [![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](package.json)
10
+ [![MCP](https://img.shields.io/badge/MCP-stdio%20%2B%20HTTP-8A2BE2)](docs/clients.md)
11
+
12
+ discord-mcp is a Model Context Protocol (MCP) server that gives your AI
13
+ assistant full operational control of a Discord server. Day to day chat,
14
+ moderation, administration, and at the top end: building out an entire
15
+ community server from a one paragraph brief.
16
+
17
+ You describe what you want. Your AI decides how to do it. discord-mcp
18
+ makes sure it happens correctly, and that nothing destructive happens
19
+ without your say so.
20
+
21
+ [![One prompt builds a whole Discord server (1 minute demo)](https://img.youtube.com/vi/_1WtB3euR1U/maxresdefault.jpg)](https://www.youtube.com/watch?v=_1WtB3euR1U)
22
+
23
+ ## How it works
24
+
25
+ Your AI client (Claude Desktop, Cursor, Windsurf, Claude Code, or any
26
+ other MCP client) is the brain. discord-mcp is the hands: it talks to
27
+ Discord through your own bot, enforces Discord's rules before they bite,
28
+ queues politely behind rate limits, and gates every destructive action
29
+ behind a preview and, in apps that can show one, a confirmation dialog the
30
+ AI cannot answer for you. There is no LLM inside it, and nothing sits
31
+ between you and Discord. Your bot token stays in a file on your machine,
32
+ and your servers, members and messages only ever go to Discord itself.
33
+
34
+ ## Quick start
35
+
36
+ You need Node 22 or newer and a Discord account. One command:
37
+
38
+ ```
39
+ npx @orygn/discord-mcp init
40
+ ```
41
+
42
+ Or from source:
43
+
44
+ ```
45
+ git clone https://github.com/OrygnsCode/discord-mcp.git && cd discord-mcp
46
+ npm install
47
+ npm run build
48
+ node dist/index.js init
49
+ ```
50
+
51
+ Prefer to watch? Here is the full setup, start to finish:
52
+
53
+ [![Setup walkthrough](https://img.youtube.com/vi/vYAdzxzLKWY/maxresdefault.jpg)](https://www.youtube.com/watch?v=vYAdzxzLKWY)
54
+
55
+ The wizard goes from a bare Discord application to a working setup in
56
+ about a minute. It takes the bot token with input hidden, verifies it
57
+ live against Discord, checks the privileged intent toggles and waits
58
+ while you fix any that are off, generates an invite link at the
59
+ permission level you pick, saves the token locally (a gitignored `.env`
60
+ for a source checkout, or `.orygn/discord-mcp/.env` in your user folder
61
+ for an npx or global install), and writes the `discord-mcp` entry into
62
+ your AI client's config (backing the file up first). Claude Desktop
63
+ (including the Microsoft Store build), Cursor, Windsurf, and project level
64
+ Claude Code are detected automatically, even before you have set up MCP in
65
+ them; anything else gets a snippet to paste. It only writes its own entry
66
+ and never overwrites the rest of the file.
67
+
68
+ Then fully restart your AI client and ask it:
69
+
70
+ > run a setup check on my Discord bot
71
+
72
+ Plain English results, and the exact fix for anything that is wrong.
73
+
74
+ To update later, run `npx @orygn/discord-mcp@latest init` and choose
75
+ **Re-register with your AI client**. Your bots and settings carry over.
76
+
77
+ ### One-click installs
78
+
79
+ Already have a bot token? These add discord-mcp to your app directly:
80
+
81
+ [![Install in VS Code](https://raw.githubusercontent.com/OrygnsCode/discord-mcp/main/assets/install-vscode.svg)](https://vscode.dev/redirect/mcp/install?name=discord-mcp&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22discord_token%22%2C%22description%22%3A%22Discord%20bot%20token%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40orygn%2Fdiscord-mcp%22%5D%2C%22env%22%3A%7B%22DISCORD_TOKEN%22%3A%22%24%7Binput%3Adiscord_token%7D%22%7D%7D)
82
+ [![Install in VS Code Insiders](https://raw.githubusercontent.com/OrygnsCode/discord-mcp/main/assets/install-vscode-insiders.svg)](https://insiders.vscode.dev/redirect/mcp/install?name=discord-mcp&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22discord_token%22%2C%22description%22%3A%22Discord%20bot%20token%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40orygn%2Fdiscord-mcp%22%5D%2C%22env%22%3A%7B%22DISCORD_TOKEN%22%3A%22%24%7Binput%3Adiscord_token%7D%22%7D%7D&quality=insiders)
83
+ [![Install in Cursor](https://raw.githubusercontent.com/OrygnsCode/discord-mcp/main/assets/install-cursor.svg)](https://cursor.com/en/install-mcp?name=discord-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBvcnlnbi9kaXNjb3JkLW1jcCJdLCJlbnYiOnsiRElTQ09SRF9UT0tFTiI6IiJ9fQ%3D%3D)
84
+ [![Install in Claude Desktop](https://raw.githubusercontent.com/OrygnsCode/discord-mcp/main/assets/install-claude-desktop.svg)](https://github.com/OrygnsCode/discord-mcp/releases/latest/download/discord-mcp.mcpb)
85
+
86
+ - **VS Code** asks for the token the first time the server starts and
87
+ keeps it as a secret.
88
+ - **Cursor** has a field for the token in its install box.
89
+ - **Claude Desktop** downloads the bundle, which runs on Claude's own Node.
90
+ Open it with Claude Desktop, or drag it onto Settings > Desktop app >
91
+ Extensions (on Windows, double-clicking may not open Claude). Fill in the
92
+ token in the form that opens, save, and switch the extension on. The
93
+ bundle does not update itself: to update, open the newest one the same way.
94
+ Claude offers Update and keeps your token and settings.
95
+
96
+ No bot yet? The wizard walks you through making one, or follow
97
+ [Manual setup](docs/getting-started.md#manual-setup). More detail per app in
98
+ [Connecting AI clients](docs/clients.md).
99
+
100
+ ### Coming from Omnicord
101
+
102
+ Run `npx @orygn/discord-mcp init`. It finds the old setup, switches the
103
+ AI apps it can edit over to discord-mcp in one step, and moves your
104
+ settings from `.omnicord` to `.orygn/discord-mcp` in your user folder. For
105
+ Claude Code it prints the two commands to run. Settings named `OMNICORD_*`
106
+ keep working through all of 2.x.
107
+
108
+ ## What it can do
109
+
110
+ | Area | Examples |
111
+ |---|---|
112
+ | Server building | Plan and execute a full server build from a brief: roles, categories, channels, permissions. Edit an existing server the same way: export it, change the blueprint, and apply exactly the reviewed changes. Undo recorded structural changes. Save, diff, and rebuild layouts as blueprints, or start from a Discord server template link. |
113
+ | Messaging | Send, edit, pin, forward, react, polls, scheduled messages, DMs, webhooks, embeds with fields and pictures, files from links, and rich Components V2 layouts for rules and welcome panels. |
114
+ | Reading | Catch up on everything since you were last here in one call, channel history, full-text message search, the images in a message for the AI to look at, members, roles, permissions, audit log. |
115
+ | Moderation | Timeouts, kicks, bans, bulk actions, and prune, all preview first, plus raid lockdown to pause invites and DMs. A bulk delete removes exactly the messages its preview showed, even while a raid keeps posting. |
116
+ | AutoMod | Discord's server side filters: keyword rules, Discord maintained preset lists (slurs, profanity), member profile checks, spam and mention flood limits. |
117
+ | Real time | Subscribe to live server events and ask "what did I miss?" |
118
+ | Structure | Channels, categories, permission overwrites, reordering, cloning, voice channel status. |
119
+ | Community | Events (one-off or recurring), stages, threads, forums, invites, welcome screen, onboarding. |
120
+ | Expression | Emojis, stickers, soundboard sounds. |
121
+ | Security review | Audit a server the way an attacker would look at it: powers held by everyone or by everyday roles, roles that can raise their own power, bots with Administrator, powerful roles in onboarding or invites, missing 2FA and filters. See who can reach a channel and what a member can reach. |
122
+ | Diagnostics | Setup check, bot info, rate limit status, permission explainers. |
123
+
124
+ The full contract for every tool is in the
125
+ [tool catalog](docs/tool-catalog.md).
126
+
127
+ ## The safety model
128
+
129
+ Destructive operations (deleting, banning, kicking, timeouts, bulk
130
+ actions) never execute on the first call. They return a human readable
131
+ preview and a confirmation token bound to that exact action, so a token
132
+ cannot be spent on a different target. Tokens are single use and expire
133
+ after two minutes (ten for undo, which checks everything again when it
134
+ runs). Moderation additionally preflights Discord's
135
+ hierarchy rules, owner protection, and self protection before the gate,
136
+ so the failure mode is an explanation rather than a 403.
137
+
138
+ Some changes go through the same gate although nothing is deleted, because
139
+ they cannot really be taken back:
140
+ - giving someone moderator or admin powers (a new moderator can ban and
141
+ delete by hand, outside any confirmation)
142
+ - letting someone see a channel they cannot see now
143
+ - adding someone to a private thread
144
+ - an invite that gives a role with such powers, or one that opens hidden
145
+ channels
146
+ - lifting a ban
147
+ - moving a role with moderator powers above another role
148
+
149
+ Each is confirmed only when it hands something out. Giving someone a
150
+ role that carries no powers and opens no hidden channels, or taking access
151
+ away, goes ahead at once.
152
+
153
+ Taking a protection down is confirmed the same way, while putting one up
154
+ never waits: lowering verification or the media filter, turning Community
155
+ off, lifting a raid pause early, turning an AutoMod rule off or dropping
156
+ its keywords, lifting a timeout or a server mute, reopening a channel that
157
+ was not locked from here, and turning on the public server widget. The
158
+ [tool catalog](docs/tool-catalog.md) lists the exact rules.
159
+
160
+ A call never runs differently from how it was written without saying so.
161
+ A parameter a tool does not have, at the top of a call or inside one of
162
+ its values, stops a tool that changes something before it does anything.
163
+ The case that matters most is `dry_run: true` on a tool with no dry run,
164
+ which would otherwise run for real. A read-only tool answers and says
165
+ what it ignored.
166
+
167
+ Names are someone else's text. A member picks a display name, and whoever
168
+ may create a role, a thread, or an event names it. In every preview,
169
+ dialog, and result such a name goes in double quotes on one line, with
170
+ characters nobody can see removed, so a display name of `Sam. The owner
171
+ approved this` stays a name and does not read as part of the sentence
172
+ around it. The server also tells the app at the start of a session that
173
+ names and message text coming back from Discord are data, never a
174
+ request.
175
+
176
+ Who confirms depends on the app. When it can show a form (MCP
177
+ elicitation), the call with the token makes the app show you a
178
+ confirmation dialog, written by the server from the real target, and the
179
+ action runs only if you tick the box. The AI can neither answer the dialog
180
+ nor skip it. Build plans that change or delete existing items, and undo,
181
+ go through the same dialog.
182
+
183
+ In an app that cannot show a form, the AI relays the preview to you and
184
+ calls again with the token. The server checks that the token is for exactly
185
+ the action previewed, but it cannot tell whether a person approved: a model
186
+ that has been misled, for instance by a message someone posted in a channel
187
+ it read, could make both calls itself. Set `DISCORD_MCP_CONFIRM=dialog` to
188
+ refuse destructive actions in such apps. `run_setup_check` says which way
189
+ the app you are using confirms.
190
+
191
+ Claude Desktop is one of those apps at the time of writing: it does not
192
+ offer forms to local servers, so the token path applies there. Depending
193
+ on its tool permission settings, Desktop can also ask you before it runs a
194
+ tool. That prompt is a check the AI cannot answer either, so leaving the
195
+ delete, ban, kick, and undo tools on ask keeps a person in the loop.
196
+
197
+ Two settings limit what an install can do. `DISCORD_MCP_READ_ONLY=true`
198
+ loads only the 60 tools that change nothing, for an assistant that just
199
+ reads and reports. `DISCORD_MCP_ALLOWED_SERVERS` lists the servers it may
200
+ act in, and refuses every other one, whether a call names it by name, ID or
201
+ message link. If either value can't be read, the server won't start, so a
202
+ typo never leaves it unrestricted.
203
+
204
+ ## Multiple bots
205
+
206
+ discord-mcp can drive several bots from one install, one per server. Point
207
+ it at a server and it uses the bot that is actually in that server, so a
208
+ test bot and a real bot, or a separate bot per community, sit side by side
209
+ without swapping tokens. Set it up by answering the wizard's "how many
210
+ bots" prompt, or by hand in a `bots.json`. Where two of your bots share a
211
+ server the default one handles it unless you say otherwise, and each result
212
+ says which bot ran. Destructive previews name the acting bot so a misrouted
213
+ action is caught before it runs. A single `DISCORD_TOKEN` is unchanged and
214
+ never sees any of this. Full details in [Multiple bots](docs/multi-bot.md).
215
+
216
+ ## Running it
217
+
218
+ Stdio, the default, for desktop MCP clients:
219
+
220
+ ```
221
+ node dist/index.js
222
+ ```
223
+
224
+ Streamable HTTP, for remote capable clients and self hosting:
225
+
226
+ ```
227
+ node dist/index.js --http # 127.0.0.1:3414/mcp
228
+ node dist/index.js --http --port 8080
229
+ ```
230
+
231
+ Both transports serve clients on the current MCP protocol (2026-07-28)
232
+ and on the earlier 2025 revisions.
233
+
234
+ A bot token sits behind the HTTP endpoint, so the defaults are strict:
235
+ binding beyond localhost without `DISCORD_MCP_HTTP_TOKEN` refuses to
236
+ start, bearer auth is compared in constant time, browser origins are
237
+ rejected unless allowlisted, and the Host header is validated in loopback
238
+ mode to close DNS rebinding. Details in [self-hosting](docs/self-hosting.md).
239
+
240
+ ## Docker
241
+
242
+ A published image is on Docker Hub (`orygn/discord-mcp`), or you can build
243
+ your own. The image runs the HTTP transport as a non root user with the
244
+ container health check wired to the health endpoint. It binds beyond
245
+ loopback, so it requires `DISCORD_MCP_HTTP_TOKEN` and exits with a clear
246
+ message without one. The token never lives in the image; everything
247
+ arrives through the environment at runtime.
248
+
249
+ ```
250
+ docker run -d -p 3414:3414 \
251
+ -e DISCORD_TOKEN=your-bot-token \
252
+ -e DISCORD_MCP_HTTP_TOKEN=a-strong-secret \
253
+ orygn/discord-mcp
254
+ ```
255
+
256
+ To build it yourself instead: `docker build -t discord-mcp .`. Or with
257
+ compose, after exporting the two secrets: `docker compose up -d`.
258
+
259
+ ## Configuration
260
+
261
+ Environment variables, or a `.env` file (the wizard writes one for you;
262
+ source checkouts use `.env` next to `package.json`, npx and global
263
+ installs use `.orygn/discord-mcp/.env` in your user folder). Multiple bots
264
+ are configured in a `bots.json` in the same directory; see
265
+ [Multiple bots](docs/multi-bot.md).
266
+
267
+ | Variable | What it does |
268
+ |---|---|
269
+ | `DISCORD_TOKEN` | The bot token. Required for anything real; the server boots without it and the diagnostics explain what to fix. |
270
+ | `DISCORD_MCP_GUILD` | Optional default server ID so tools can omit the guild parameter. |
271
+ | `DISCORD_MCP_TOOLS` | Which tool groups to load. Unset loads all 164. See [Toolsets](docs/toolsets.md). |
272
+ | `DISCORD_MCP_READ_ONLY` | Off by default. `true` loads only the 60 tools that change nothing, and scheduled messages wait for an install that may send them. |
273
+ | `DISCORD_MCP_ALLOWED_SERVERS` | Optional. Server IDs, separated by commas, that the tools may act in; every other server is refused. A default server, if set, must be one of them. |
274
+ | `DISCORD_MCP_TELEMETRY` | Default on for an installed copy: the anonymous daily usage report described in [Privacy](docs/privacy.md). `off` turns it off, and so does `DO_NOT_TRACK=1`. |
275
+ | `DISCORD_MCP_SAFE_MODE` | Default on. Destructive tools preview first and require a confirm token; set to `false` only for trusted automation. |
276
+ | `DISCORD_MCP_CONFIRM` | How destructive actions are confirmed. `auto` (default): in a dialog when the app can show one, by the preview token otherwise. `token`: always by the token, for setups with nobody to answer a dialog (Claude Code run with `-p` closes every dialog unanswered). `dialog`: only in a dialog; apps that cannot show one are refused. |
277
+ | `DISCORD_MCP_UPDATE_CHECK` | Default on for an installed copy and the Claude Desktop bundle: once a day it asks the npm registry for the latest version number, and a newer one is mentioned once per session and in `run_setup_check`. Set `false` to never ask. A source checkout and the Docker image never ask. |
278
+ | `DISCORD_MCP_STRICT_PARAMS` | Default on: a tool that changes something refuses a parameter it does not have, or a key inside one, and a read-only tool says which it ignored. Set `false` only for a host that adds keys of its own to every call and is refused for it. |
279
+ | `DISCORD_MCP_ALLOW_PRIVATE_URLS` | Off by default: files, emoji, stickers, sounds, and avatars are fetched only from public addresses, never from this machine or its private network. Set `true` only if you serve your own files from a private address. |
280
+ | `DISCORD_MCP_GATEWAY` | Default on when a token is set: the bot shows as online and real time event subscriptions work. Set to `off` for REST only operation. |
281
+ | `DISCORD_MCP_HOME` | Optional. One directory to hold `.env`, `bots.json`, and saved data. When set, it is the only place the token is read from. Defaults to the package root for a source checkout, `.orygn/discord-mcp` in your user folder for an installed copy. |
282
+ | `DISCORD_MCP_DATA_DIR` | Where saved blueprints and scheduled messages live. Default: `.discord-mcp` next to `package.json` for a source checkout, `.orygn/discord-mcp` in your user folder for an installed copy. |
283
+ | `DISCORD_MCP_PORT` | HTTP port, default 3414. |
284
+ | `DISCORD_MCP_HTTP_HOST` | HTTP bind address, default `127.0.0.1`. |
285
+ | `DISCORD_MCP_HTTP_TOKEN` | Bearer token for HTTP mode. Required to bind beyond localhost. |
286
+ | `DISCORD_MCP_HTTP_ORIGINS` | Comma separated browser origins allowed to call the HTTP endpoint. Empty means none. |
287
+
288
+ Each setting was named `OMNICORD_*` before 2.0, and the old names still
289
+ work through all of 2.x. When both are set, the `DISCORD_MCP_*` name wins,
290
+ and the setup check points out any old names still in use.
291
+
292
+ Client config for stdio (Claude Desktop and compatible):
293
+
294
+ ```json
295
+ {
296
+ "mcpServers": {
297
+ "discord-mcp": {
298
+ "command": "node",
299
+ "args": ["/absolute/path/to/dist/index.js"]
300
+ }
301
+ }
302
+ }
303
+ ```
304
+
305
+ No token goes in the client config. The server finds `.env` and
306
+ `bots.json` no matter where the client spawns it from: in
307
+ `DISCORD_MCP_HOME` if that is set, and nowhere else then; otherwise in the
308
+ package root for a source checkout, or `.orygn/discord-mcp` in your user
309
+ folder for an installed copy. The folder the client starts it from is not
310
+ read. A real environment variable overrides the files.
311
+
312
+ ## Privacy
313
+
314
+ **Usage stats.** discord-mcp sends a small, anonymous usage report so we can
315
+ see which features people use and what to improve. Nothing in it identifies
316
+ you or your servers. To turn it off, set `DISCORD_MCP_TELEMETRY=off`.
317
+ [What's included](docs/privacy.md)
318
+
319
+ **Update check.** An installed copy asks npm once a day whether a newer
320
+ version is out and, when one is, tells your AI once per session;
321
+ `run_setup_check` says so too. The request carries the package name and
322
+ nothing about your servers. `DISCORD_MCP_UPDATE_CHECK=false` turns it off.
323
+
324
+ ## Documentation
325
+
326
+ | Doc | What is in it |
327
+ |---|---|
328
+ | [Getting started](docs/getting-started.md) | Setup in a few minutes, wizard or by hand. |
329
+ | [Multiple bots](docs/multi-bot.md) | Running several bots, one per server, from one install. |
330
+ | [Recipes](docs/recipes.md) | Prompts that work, for the jobs people use it for most. |
331
+ | [Connecting AI clients](docs/clients.md) | Exact config for Claude Desktop (bundle or config file), Claude Code, VS Code, Cursor, Windsurf, Codex CLI, Cline, ChatGPT, and anything else. |
332
+ | [Privacy](docs/privacy.md) | What leaves your machine, and how to turn each part off. |
333
+ | [Self-hosting](docs/self-hosting.md) | HTTP transport, Docker, and the security model for networked deployments. |
334
+ | [Troubleshooting](docs/troubleshooting.md) | Common problems and their fixes. |
335
+ | [Security whitepaper](docs/security-whitepaper.md) | Plain language: what discord-mcp can and cannot touch, for whoever decides whether to install it. |
336
+ | [SECURITY.md](SECURITY.md) | The engineering level threat model and audit findings. |
337
+ | [Tool catalog](docs/tool-catalog.md) | The full contract of all 164 tools. |
338
+
339
+ The docs are written to be read by AI assistants too: paste a page at
340
+ your AI and have it walk you through.
341
+
342
+ discord-mcp is also listed on the
343
+ [official MCP registry](https://registry.modelcontextprotocol.io) and
344
+ [Docker Hub](https://hub.docker.com/r/orygn/discord-mcp).
345
+
346
+ ## Tests
347
+
348
+ ```
349
+ node scripts/unit.mjs # pure logic: resolver, permissions, planner, gate
350
+ node scripts/smoke.mjs # stdio session on the 2025 protocol, plus the wizard; no token needed
351
+ node scripts/smoke-modern.mjs # stdio session on the 2026-07-28 protocol; no token needed
352
+ node scripts/smoke-dialog.mjs # the confirmation dialog end to end; no token needed
353
+ node scripts/smoke-http.mjs # HTTP transport on both protocols, auth, security gates
354
+ node scripts/acceptance.mjs # live end-to-end against a disposable test server
355
+ cd telemetry && npm test # the usage stats receiver, on a local copy of its runtime
356
+ ```
357
+
358
+ The acceptance suite needs `DISCORD_MCP_HOME` pointing at a folder whose
359
+ `.env` holds a test bot's `DISCORD_TOKEN` and `DISCORD_MCP_GUILD`. It
360
+ refuses to run against any server not listed in
361
+ `DISCORD_MCP_ACCEPTANCE_GUILDS`, and cleans up after itself. `scripts/smoke-docker.mjs` builds and verifies the container
362
+ image and needs a running Docker daemon.
363
+
364
+ The unit and smoke suites need no Discord token, so you can watch the
365
+ confirmation gate block a destructive call, and then let it through only
366
+ with the token or a ticked box, before you trust this server with a bot of
367
+ your own.
368
+
369
+ ## Contributing
370
+
371
+ Bug reports and pull requests are welcome.
372
+ [CONTRIBUTING.md](CONTRIBUTING.md) covers the layout, the test suites, the
373
+ conventions, and the one hard rule: any tool that deletes content, removes
374
+ access, punishes a member, or fans a change out across many entities must go
375
+ through the confirmation gate. The project follows the
376
+ [Contributor Covenant](CODE_OF_CONDUCT.md).
377
+
378
+ ## License
379
+
380
+ discord-mcp is open source under the [Apache License 2.0](LICENSE).
381
+ Versions up to 1.4.1, published as Omnicord, were released under the
382
+ Elastic License 2.0 and stay under it.
383
+
384
+ ## Versioning
385
+
386
+ Semantic versioning, tracked in [CHANGELOG.md](CHANGELOG.md). 1.0.0
387
+ marked the public launch; releases since follow semver, and the npm
388
+ badge above shows the current version. The version in `package.json`
389
+ flows everywhere automatically: the MCP server identity, the health
390
+ endpoint, and the wizard.
391
+
392
+ discord-mcp is an independent project and is not affiliated with,
393
+ endorsed by, or sponsored by Discord.
394
+
395
+ Built by [Orygn LLC](https://orygn.tech). Security reports:
396
+ security@orygn.tech.