discord-sovereign-mcp

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.

Related MCP server: Discord Server Creator MCP

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)

1. Create an application at https://discord.com/developers/applications.

2. Under Bot: create the bot, copy the token, enable SERVER MEMBERS INTENT and MESSAGE CONTENT INTENT.

3. 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.)

4. DISCORD_TOKEN=<token> in .env: DISCORD_TOKEN_TYPE=auto detects bot vs user.

Token setup: user token via OAuth2

1. Create an application; under OAuth2 -> General add a redirect http://localhost:8788/callback.

2. Set DISCORD_OAUTH2_CLIENT_ID, DISCORD_OAUTH2_CLIENT_SECRET, DISCORD_OAUTH2_REDIRECT_URI in .env.

3. 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

AI client configs

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.