MCP 服务器

discord-sovereign-mcp

Enables full-lifecycle Discord server management from any LLM, including creation, administration, and scaffolding, with a sovereignty guard ensuring mutations only occur when the client has the highest role.

README

Full-lifecycle Discord MCP server for any LLM: gated by a Sovereignty Guard that only mutates when the client holds the #1 (highest) role in the guild's role hierarchy.

Why a sovereignty guard? Discord's permission model is hierarchical: role position, not permission flags, decides who can do what. The single most common cause of Missing Permissions failures in LLM-driven admin bots is acting from a role that thinks it has permissions but sits below the roles it tries to manage. This server refuses to act until the client provably sits at the top of the ladder.

One-click install

npx discord-sovereign-mcp@latest --install

That's it. The installer wires the server into Claude Code, Claude Desktop, Codex, opencode, Cursor, Windsurf, Continue, Google Antigravity, and VS Code: interactive picker by default, --all if you want everything, backups before every write, idempotent on re-run.

npx discord-sovereign-mcp@latest --install --all: every client, no prompts
npx discord-sovereign-mcp@latest --install --client codex,opencode --dry-run: preview
Full guide: docs/INSTALL.md

Prefer manual setup? Copy the ready-made config for your client from examples/mcp/: every file, every client, the same npx invocation.

What you get

46 tools across control, guilds, channels, members, scaffolding, and OAuth: snake_case, discord_-prefixed, schema-strict, documented in TOOLS.md.
Sovereign Control Guard: every destructive tool is dry_run by default and must pass discord_assert_sovereignty before executing with dry_run: false, enforced server-side.
One-shot server scaffolding: discord_scaffold_server builds roles, categories, channels, and permission overwrites from a declarative template (minimal / community / gaming / support).
OAuth2 bootstrap for user-token mode (--oauth) and safety rails: guild allowlist, audit-log reasons, idempotency checks, and dry_run previews that return the exact API payload.

Quick start

# run directly (stdio)
npx discord-sovereign-mcp@latest

# run with OAuth2 user-token bootstrap
npx discord-sovereign-mcp@latest --oauth

# from source
npm install
cp .env.example .env        # then edit: DISCORD_TOKEN (or OAuth2 vars)
npm run build
npm test                    # 80 unit tests

Token setup: bot (recommended for servers you own)

Create an application at https://discord.com/developers/applications.
Under Bot: create the bot, copy the token, enable SERVER MEMBERS INTENT and MESSAGE CONTENT INTENT.
Under OAuth2 -> URL Generator: scope bot, permissions Administrator, invite the bot to your server. (Administrator is required for server-scoped operations; the guard still enforces role position.)
DISCORD_TOKEN=<token> in .env: DISCORD_TOKEN_TYPE=auto detects bot vs user.

Token setup: user token via OAuth2

Create an application; under OAuth2 -> General add a redirect http://localhost:8788/callback.
Set DISCORD_OAUTH2_CLIENT_ID, DISCORD_OAUTH2_CLIENT_SECRET, DISCORD_OAUTH2_REDIRECT_URI in .env.
npx discord-sovereign-mcp@latest --oauth: opens the authorization URL, waits for the callback, and writes the user token into .env (DISCORD_TOKEN_TYPE=oauth2).

Run

npm run dev            # tsx, stdio transport
npm run start          # built dist/, stdio transport
TRANSPORT=http npm run start    # HTTP transport (POST /mcp, GET /health)

The Sovereignty Guard

discord_assert_sovereignty: read-only verdict: prints the full role ladder with positions and flags the client role. Controlled = client owns the guild (user mode) or holds the #1 role (bot mode).
discord_elevate_control: moves the client role to the top of the ladder, then re-verifies. Never fails silently: if the API rejects the reorder, the error explains that a human must drag the role above the roles it couldn't outrank.
Every destructive tool runs the same gate (assertControl) before its first mutating call when dry_run: false: awaited server-side, so a guard failure can never be dropped.

Scaffolding

discord_scaffold_server builds a whole server from a template in one call:

{
  "guild_id": "1234567890",
  "template": "community",          // minimal | community | gaming | support
  "dry_run": false
}

It executes in safe order: roles lowest-first, then categories, then channels (with parent wiring), then permission overwrites, guarding once before the first step. Each step is isolated: on failure the tool returns steps_total / steps_completed / steps_failed plus the already-created role/channel IDs so a partial scaffold can be reconciled by hand.

Environment variables

Variable	Default	Description
`DISCORD_TOKEN`	none	Bot or OAuth2 user token (required).
`DISCORD_TOKEN_TYPE`	`auto`	`auto` \| `bot` \| `oauth2` \| `user`. `auto` detects bot vs user from the token.
`DISCORD_ALLOWED_GUILDS`	(empty = all)	Comma-separated guild IDs. When set, every tool refuses guilds outside the list, even if sovereignty is held.
`TRANSPORT`	`stdio`	`stdio` \| `http`.
`HTTP_HOST` / `HTTP_PORT`	`127.0.0.1` / `3000`	HTTP transport bind address/port.
`DISCORD_OAUTH2_CLIENT_ID`	none	OAuth2 application client ID.
`DISCORD_OAUTH2_CLIENT_SECRET`	none	OAuth2 application client secret.
`DISCORD_OAUTH2_REDIRECT_URI`	`http://localhost:8788/callback`	Must match the redirect registered in the Discord developer portal.
`DISCORD_OAUTH2_PORT`	`8788`	Local callback port used by `--oauth`.
`AUDIT_REASON`	`via discord-sovereign-mcp`	Audit-log reason stamped on actions.
`LOG_LEVEL`	`info`	`info` \| `debug` \| `warn` \| `error`.

AI client configs

Client	Config file	Where it goes
Claude Code	`claude-code.json`	`.mcp.json` at the repo root (or `~/.claude.json`)
Claude Desktop	`claude-desktop-config.json`	menu: Claude -> Settings -> Developer
Codex CLI	`codex-config.toml`	`~/.codex/config.toml` (user) or `.codex/config.toml` (project)
opencode	`opencode.json`	`opencode.json` in the project (or `~/.config/opencode/`)
Cursor	`cursor-mcp.json`	`.cursor/mcp.json`
Windsurf	`windsurf-mcp.json`	`.windsurf/mcp_config.json`
Continue	`continue-config.json`	`~/.continue/config.json`
Google Antigravity	`antigravity-config.json`	Project MCP settings

Ready-to-paste files: examples/mcp/. Every client invokes the server the same way: npx discord-sovereign-mcp@latest.

Development

npm run typecheck   # tsc --noEmit
npm run test        # vitest run
npm run install:mcp # run the installer locally (tsx)
npm run oauth       # OAuth2 user-token bootstrap
npm run eval        # offline registry checks (add --live for protocol checks)

Docs

TOOLS.md: full reference for all 46 tools (generated).
docs/INSTALL.md: the installer: flags, token resolution, what gets written.
docs/SPEC.md: design spec: architecture, threat model, guard semantics, tool contracts.
docs/RECIPES.md: end-to-end recipes for common workflows.
SECURITY.md: threat model, token handling, and reporting policy.

License

MIT: see LICENSE.