Discord Agent

An autonomous AI agent that lives inside Discord. Mention it, ask it in plain language, and it inspects the server, plans multi-step actions, executes them through Discord API tools, verifies the result, and reports back — as a real administrator would.

It is multi-guild by design: every operation is hard-scoped to the guild where it was invoked, with no possibility of mixing context, memory, or permissions across servers.

User:  @Agent create a Development category with frontend, backend, devops,
       and code-review channels, plus a Dev role that can access them.
Agent: Done. Created the Development category with 4 channels and the Dev role,
       and configured permissions. Everything verified.

Features

• Autonomous planning & execution — users describe goals, not API calls.

• LLM-agnostic — OpenAI, Anthropic, Gemini, OpenRouter, DeepSeek, Ollama, or any OpenAI-compatible endpoint.

• Multi-guild isolation — every query, cache entry, and memory record is namespaced by guild.

• MCP-style tool layer — discord.guild.*, discord.channel.*, discord.role.*, discord.permission.*, discord.message.*, discord.member.*, discord.moderation.*, discord.thread.*, discord.forum.*, discord.search.*, discord.audit.*, discord.analytics.*, discord.memory.*, discord.automation.*, discord.schedule.*, discord.server.*, discord.bulk.*, discord.notebook.*, discord.embed.*.

• Permission intelligence — explains why a member can or cannot act.

• Safety gates — risk classification, configurable confirmation levels, dry-run/plan mode, idempotent ensure_* operations, authorization independent of the LLM.

• Prompt-injection resistance — all Discord content is treated as untrusted; rules and guild boundaries cannot be overridden.

• Guild-scoped memory — "remember that …", "forget that …", "what do you remember?".

• Event automations & scheduled tasks — welcome messages, reactions, weekly summaries, reaction roles, and semantic condition matching.

• Notebook / economy — per-guild & per-member key/value store for XP, coins, levels, drafts, and tickets; optional passive XP with cooldown; instant !xp / !balance / !level queries.

• Buttons, modals & embeds — send messages with action buttons, interactive forms, and rich embeds.

• Reaction GIFs — anime reaction GIFs (kiss/hug/hit/pat/…) posted in embeds with playful captions; plus server emoji & sticker tools.

• Audit trail — structured run/action history per guild.

• CLI diagnostics — agent doctor, agent status, agent guilds, agent capabilities, agent test.

Related MCP server: discord-mcp

Quick start

1. Create a Discord application

1. Go to https://discord.com/developers/applications and create a New Application.

2. Under Bot, create a bot and copy the token.

3. Enable the required Privileged Gateway Intents:

   • Server Members Intent

   • Message Content Intent

4. Use the OAuth2 → URL Generator to invite the bot with bot scope and the permissions it needs (e.g. Manage Channels, Manage Roles, Manage Messages). The bot will only ever do what its Discord permissions allow.

2. Configure

cp .env.example .env
# edit .env and set at minimum:
#   DISCORD_BOT_TOKEN=
#   LLM_PROVIDER=openai
#   LLM_API_KEY=
#   LLM_MODEL=gpt-4o-mini

3. Run

Docker:

docker compose up --build

Local development:

npm install
npm run dev

Production build:

npm run build
npm start

4. Use it

Mention the bot in any channel:

@Agent organize this server
@Agent create a private staff section
@Agent why can't John send messages in #general?
@Agent audit the server permissions
@Agent remember that release channels should always be read-only

Prefix a request with plan / preview / dry-run to get a plan without executing, or with audit / analyze for read-only analysis.

Commands & diagnostics

npm run cli -- doctor         # environment + configuration health check
npm run cli -- status         # configuration summary
npm run cli -- guilds         # list known guilds
npm run cli -- capabilities   # list all tools by namespace and risk
npm run cli -- config         # show resolved config (secrets redacted)
npm run cli -- test           # quick self-test

Docker

The project ships a multi-stage Dockerfile (build in a full toolchain image, run in a slim image as the node user) and a docker-compose.yml.

# Build and run with docker compose
docker compose up --build -d

# Or build the image directly
docker build -t discord-agent .

# Run the self-test inside the built image
docker run --rm discord-agent node dist/cli/cli.js test

The SQLite database is persisted in the agent-data volume at /app/data/agent.sqlite. See docs/DEPLOYMENT.md.

A prebuilt image is published to the GitHub Container Registry by the Docker workflow on every push to main and every tag:

docker pull ghcr.io/NacreousDawn596/DiscordMCP:main

The CI workflow runs typecheck, the test suite, and a production build on every push and PR.

Configuration

See .env.example for the full list. Key settings:

Connect to OpenCode (MCP)

Yes — the discord.* tool suite can be exposed to opencode (or any MCP client: Claude Code, Cursor, etc.) as a real Model Context Protocol server over stdio. When connected, you can drive your Discord server from prompts like:

use the discord-agent tools to create a "Development" category with
#frontend, #backend and #devops in guild 123456789

How it works

The MCP server (npm run mcp) boots the same Discord bot, logs in with your token, and serves all 127 tools over stdin/stdout. Each tool takes an optional guild_id so the same server can manage every guild the bot is in.

Important: MCP calls run as the bot itself (admin context), scoped to whatever the bot can actually do. Destructive moderation (ban/kick/purge) still requires ENABLE_MODERATION=true. There is no interactive confirmation channel over MCP, so actions run immediately.

Step 1 — Build (or run with tsx)

npm install
npm run build        # produces dist/mcp/entry.js

Step 2 — Configure opencode

Add an mcp entry to your opencode config. This can be the project config (opencode.json) or your global config (~/.config/opencode/opencode.json).

Option A — rely on the project .env (recommended):

// opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "discord-agent": {
      "type": "local",
      "command": ["node", "dist/mcp/entry.js"],
      "cwd": "/absolute/path/to/discord-agent",
      "enabled": true,
      "timeout": 30000
    }
  }
}

Set cwd to the project directory so the server loads your .env (which holds DISCORD_BOT_TOKEN and, optionally, MCP_DEFAULT_GUILD_ID).

Option B — pass the token explicitly (no .env needed):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "discord-agent": {
      "type": "local",
      "command": ["node", "dist/mcp/entry.js"],
      "cwd": "/absolute/path/to/discord-agent",
      "environment": {
        "DISCORD_BOT_TOKEN": "your-bot-token",
        "MCP_DEFAULT_GUILD_ID": "123456789"
      },
      "enabled": true,
      "timeout": 30000
    }
  }
}

Set timeout above the default 5s — the server logs the bot into Discord before answering, which can take a few seconds.

Dev (no build): use "command": ["npx", "tsx", "src/mcp/entry.ts"].

Step 3 — Restart opencode

Restart opencode so it picks up the new MCP server. You can verify the connection with /mcp (or by asking: list the discord-agent tools).

Step 4 — Use it

Every tool is prefixed discord_. Examples:

create a #welcome channel in guild 123456789 using discord-agent
list the roles in guild 123456789
audit the permissions in guild 123456789

If MCP_DEFAULT_GUILD_ID is set (or the bot is in exactly one guild), you can omit guild_id:

using discord-agent, create a Development category with #frontend and #backend

MCP options

See docs/CONFIGURATION.md for the full tool catalog and npm run cli -- capabilities for the live list.

Architecture

Discord ── message/mention/interaction ──► Discord Agent
                                            ├── Context Manager
                                            ├── LLM / Agent Runtime (tool loop)
                                            ├── Memory (guild-scoped)
                                            ├── Planner + validation
                                            ├── Permission awareness
                                            ├── MCP Tool Layer
                                            └── Execution Engine ──► Discord API

See docs/ARCHITECTURE.md, docs/CONFIGURATION.md, docs/SECURITY.md, and docs/DEPLOYMENT.md for details. For ready-to-use example prompts and provider configs, see examples/.

Testing

npm test

Unit tests cover guild isolation, authorization, permission calculation, risk classification, memory isolation, tool validation, plan validation, and prompt injection defenses.

Security

The bot has immutable boundaries: it never exposes its token, never bypasses Discord permissions, never crosses guild boundaries, never lets message content override policy, never authorizes privileged actions from unauthorized users, and never claims success without verifying state. See docs/SECURITY.md.

License

MIT