Discord Server Creator

A Model Context Protocol (MCP) server that gives AI agents full control over Discord server creation and configuration. Exposes 36 tools covering guild lifecycle, channels, roles, members, content, messages, templates, and a declarative blueprint engine.

• Runtime: Bun 1.1+
• Transport: stdio (local process)
• Status: 183 tests passing — see specs.md §14 for phase breakdown

Quick Start

Prerequisites

• Bun 1.1+
• A Discord Bot Token

1. Install

git clone <repo> dc-server-creator
cd dc-server-creator
bun install

2. Create a Discord Bot

1. Go to https://discord.com/developers/applications
2. New Application → name it (e.g. "Server Creator")
3. Bot tab → Add Bot
4. Under Privileged Gateway Intents, enable Server Members Intent (required for member tools)
5. Copy the bot token
6. Invite the bot to a test guild via the OAuth2 URL Generator:
   • Scopes: bot
   • Permissions: Administrator (for testing) or select specific permissions

3. Register with your MCP Client

opencode — add to your opencode.json (project-level or ~/.config/opencode/opencode.json):

{
  "mcp": {
    "discord-server-creator": {
      "type": "local",
      "command": ["bun", "run", "/absolute/path/to/dc-server-creator/src/index.ts"],
      "environment": {}
    }
  }
}

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "discord-server-creator": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/dc-server-creator/src/index.ts"]
    }
  }
}

Replace /absolute/path/to/ with the actual path from pwd (or cd on Windows).

Claude Code (plugin) — install as a plugin with automatic skill loading:

# Add the marketplace (one-time)
/plugin marketplace add ZepioCs/dc-server-creator-mcp

# Install the plugin
/plugin install dc-server-creator@dc-server-creator-mcp

The plugin installs a skill (dc-server-creator) that teaches Claude Code when and how to use all 36 tools. After installation, Claude automatically activates the skill when you describe Discord server tasks.

You still need to configure the bot token via configure_bot({ action: "setup", token }) — see step 4.

4. First Run

1. Start your MCP client (opencode / Claude Desktop)
2. The AI agent (or you) calls:

   configure_bot({ action: "setup", token: "Bot <your-token>" })
   

3. Server responds with the bot's identity and ready status
4. Try:

   list_guilds({})
   

   to see all guilds the bot is in.

5. One-Shot Server Creation

Apply a ready-made blueprint — no per-channel/role calls needed:

apply_server_blueprint({
  blueprint: { /* see examples/blueprints/ */ },
  dryRun: true   // validate first without making changes
})

See examples/blueprints/ for pre-built server templates (gaming community, dev team, support server, community default).

Scripts

bun start          # run the MCP server (stdio)
bun run typecheck  # TypeScript type-check
bun run lint       # Biome lint
bun test           # run all tests (183+)
bun test --coverage # run with coverage report

Tool Catalog

Group	Tools	Count
Auth	configure_bot, get_auth_status	2
Guild	list_guilds, get_guild, create_guild, modify_guild, delete_guild	5
Channel	list_channels, create_channel, create_category_with_channels, modify_channel, delete_channel, set_channel_permissions, create_invite	7
Role	list_roles, create_role, modify_role, delete_role, assign_role	5
Member	list_members, search_members, get_member, modify_member, moderate_member	5
Messages	send_message, edit_message, delete_message, get_messages	4
Content	manage_emoji, manage_sticker, manage_webhook, execute_webhook	4
Template	manage_template, create_guild_from_template	2
Blueprint	apply_server_blueprint	1
Log	get_action_log	1
Total		36

See specs.md §5 for full input/output schemas.

Error Handling

Every error returns a structured JSON payload with:

{
  "error": "DISCORD_FORBIDDEN",
  "message": "Bot lacks MANAGE_CHANNELS permission",
  "hint": "The bot lacks the required permission. Check the bot's role permissions in the server.",
  "retryable": false,
  "traceId": "abc-123"
}

The hint field explains the likely cause and how to fix it. See specs.md §7 for the full error hierarchy.

Blueprint Engine

The apply_server_blueprint tool accepts a declarative JSON blueprint to create an entire server in one call — including roles, categories, channels, permissions, emoji, stickers, webhooks, and onboarding messages.

{
  "guild": { "name": "My Server", "verificationLevel": 1 },
  "roles": [{ "name": "Admin", "permissions": ["ADMINISTRATOR"] }],
  "categories": [{ "name": "General", "channels": [{ "name": "chat", "type": "text" }] }],
  "messages": [{ "channelName": "chat", "content": "Welcome!" }]
}

• dryRun: validates without making API calls
• continueOnError: keep going after failures
• rollbackOnError: undo completed steps on failure

Execution order: guild → @everyone → roles → categories → children → standalone channels → guild settings → emoji → stickers → webhooks → messages.

See specs.md §6 for the full BlueprintSpec schema and execution order.

Project Layout

src/           # TypeScript source
├── index.ts           # Entry point
├── server.ts          # MCP server + tool registration
├── discord/           # Discord client, errors, mappings
├── engine/            # Blueprint engine (plan, apply, validate)
├── schemas/           # Zod schemas for all tools
├── tools/             # Tool handlers (one file per group)
└── utils/             # Logger, action log, env, retry
tests/         # Test suite
├── unit/              # Unit tests
└── integration/       # Integration tests (schema validation, etc.)
examples/      # User-facing examples
└── blueprints/        # Pre-built server blueprints

Implementation Status

Phase	Status	What
1 — Foundation	✅	Project scaffold, Discord client, auth, basic guild tools
2 — Configuration	✅	All channel/role/member tools, full guild CRUD
3 — Content + Templates	✅	Emoji, sticker, webhook, template tools
4 — Blueprint Engine	✅	Blueprint schema, validation, plan, apply with rollback, messages
5 — Polish	🔧	Error audit (done), perf test (done), docs (done), coverage, mock tests

See specs.md §14 for full details.