Discord Agent

Ein autonomer KI-Agent, der in Discord lebt. Erwähne ihn, frag ihn in einfacher Sprache, und er untersucht den Server, plant mehrstufige Aktionen, führt sie über Discord-API-Tools aus, überprüft das Ergebnis und meldet zurück — wie es ein echter Administrator tun würde.

Es ist von Natur aus Multi-Guild: Jede Operation ist strikt auf die Guild beschränkt, in der sie aufgerufen wurde, ohne die Möglichkeit, Kontext, Speicher oder Berechtigungen über Server hinweg zu vermischen.

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

• Autonome Planung & Ausführung — Benutzer beschreiben Ziele, keine API-Aufrufe.

• LLM-agnostisch — OpenAI, Anthropic, Gemini, OpenRouter, DeepSeek, Ollama oder ein beliebiger OpenAI-kompatibler Endpunkt.

• Multi-Guild-Isolation — jede Abfrage, jeder Cache-Eintrag und jeder Speichereintrag ist in einem Guild-Namespace abgelegt.

• MCP-artige Tool-Schicht — 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.*.

• Berechtigungs-Intelligenz — erklärt warum ein Mitglied handeln kann oder nicht.

• Sicherheits-Gates — Risikoklassifizierung, konfigurierbare Bestätigungsstufen, Dry-Run-/Plan-Modus, idempotente ensure_*-Operationen, Autorisierung unabhängig vom LLM.

• Prompt-Injection-Resistenz — sämtliche Discord-Inhalte werden als nicht vertrauenswürdig behandelt; Regeln und Guild-Grenzen können nicht außer Kraft gesetzt werden.

• Guild-gebundener Speicher — „erinnere dich, dass …“, „vergiss, dass …“, „woran erinnerst du dich?“.

• Event-Automatisierungen & geplante Aufgaben — Begrüßungsnachrichten, Reaktionen, wöchentliche Zusammenfassungen.

• Audit-Trail — strukturierte Ausführungs-/Aktionshistorie pro Guild.

• CLI-Diagnose — agent doctor, agent status, agent guilds, agent capabilities, agent test.

Related MCP server: discord-mcp

Quick start

1. Discord-Anwendung erstellen

1. Gehe zu https://discord.com/developers/applications und erstelle eine Neue Anwendung.

2. Erstelle unter Bot einen Bot und kopiere den Token.

3. Aktiviere die erforderlichen Privileged Gateway Intents:

   • Server Members Intent

   • Message Content Intent

4. Verwende den OAuth2 → URL Generator, um den Bot mit dem bot-Scope und den benötigten Berechtigungen einzuladen (z. B. Manage Channels, Manage Roles, Manage Messages). Der Bot wird nur das tun, was seine Discord-Berechtigungen erlauben.

2. Konfigurieren

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. Ausführen

Docker:

docker compose up --build

Lokale Entwicklung:

npm install
npm run dev

Produktions-Build:

npm run build
npm start

4. Verwenden

Erwähne den Bot in einem beliebigen Kanal:

@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

Stelle einer Anfrage plan / preview / dry-run voran, um einen Plan ohne Ausführung zu erhalten, oder audit / analyze für eine schreibgeschützte Analyse.

Befehle & Diagnose

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

Das Projekt enthält ein mehrstufiges Dockerfile (Build in einem vollständigen Toolchain-Image, Ausführung in einem schlanken Image als node-Benutzer) sowie eine 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

Die SQLite-Datenbank wird im Volume agent-data unter /app/data/agent.sqlite gespeichert. Siehe docs/DEPLOYMENT.md.

Ein vorgefertigtes Image wird bei jedem Push auf main und jedem Tag vom Docker-Workflow in die GitHub Container Registry veröffentlicht:

docker pull ghcr.io/NacreousDawn596/DiscordMCP:main

Der CI-Workflow führt bei jedem Push und PR Typprüfung, die Testsuite und einen Produktions-Build aus.

Konfiguration

Siehe .env.example für die vollständige Liste. Wichtige Einstellungen:

Verbindung zu OpenCode (MCP)

Ja — die discord.*-Tool-Suite kann als echter Model Context Protocol Server über stdio für opencode (oder jeden MCP-Client: Claude Code, Cursor usw.) bereitgestellt werden. Nach der Verbindung kannst du deinen Discord-Server mit Aufforderungen wie diesen steuern:

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

So funktioniert es

Der MCP-Server (npm run mcp) startet denselben Discord-Bot, meldet sich mit deinem Token an und stellt alle 127 Tools über stdin/stdout bereit. Jedes Tool akzeptiert eine optionale guild_id, sodass derselbe Server jede Guild verwalten kann, in der der Bot ist.

Wichtig: MCP-Aufrufe laufen als der Bot selbst (Admin-Kontext), beschränkt auf das, was der Bot tatsächlich tun kann. Destruktive Moderation (Bannen/Kicken/Löschen) erfordert weiterhin ENABLE_MODERATION=true. Über MCP gibt es keinen interaktiven Bestätigungskanal, daher werden Aktionen sofort ausgeführt.

Schritt 1 — Build (oder mit tsx ausführen)

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

Schritt 2 — opencode konfigurieren

Füge einen mcp-Eintrag zu deiner opencode-Konfiguration hinzu. Das kann die Projektkonfiguration (opencode.json) oder deine globale Konfiguration (~/.config/opencode/opencode.json) sein.

Option A — sich auf die Projekt-.env verlassen (empfohlen):

// 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
    }
  }
}

Setze cwd auf das Projektverzeichnis, damit der Server deine .env lädt (die DISCORD_BOT_TOKEN und optional MCP_DEFAULT_GUILD_ID enthält).

Option B — Token explizit übergeben (keine .env erforderlich):

{
  "$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
    }
  }
}

Setze timeout über den Standardwert von 5s — der Server meldet den Bot bei Discord an, bevor er antwortet, was einige Sekunden dauern kann.

Dev (ohne Build): verwende "command": ["npx", "tsx", "src/mcp/entry.ts"].

Schritt 3 — opencode neu starten

Starte opencode neu, damit es den neuen MCP-Server übernimmt. Du kannst die Verbindung mit /mcp überprüfen (oder indem du fragst: list the discord-agent tools).

Schritt 4 — Verwenden

Jedes Tool hat das Präfix discord_. Beispiele:

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

Wenn MCP_DEFAULT_GUILD_ID gesetzt ist (oder der Bot in genau einer Guild ist), kannst du guild_id weglassen:

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

MCP-Optionen

Siehe docs/CONFIGURATION.md für den vollständigen Tool-Katalog und npm run cli -- capabilities für die Live-Liste.

Architektur

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

Siehe docs/ARCHITECTURE.md, docs/CONFIGURATION.md, docs/SECURITY.md und docs/DEPLOYMENT.md für Details. Vorgefertigte Beispiel-Prompts und Provider-Konfigurationen findest du in examples/.

Tests

npm test

Unit-Tests decken Guild-Isolation, Autorisierung, Berechtigungsberechnung, Risikoklassifizierung, Speicher-Isolation, Tool-Validierung, Plan-Validierung und Prompt-Injection-Abwehr ab.

Sicherheit

Der Bot hat unveränderliche Grenzen: Er gibt niemals sein Token preis, umgeht niemals Discord-Berechtigungen, überschreitet niemals Guild-Grenzen, lässt niemals zu, dass Nachrichteninhalte Richtlinien außer Kraft setzen, autorisiert niemals privilegierte Aktionen von nicht autorisierten Benutzern und behauptet niemals Erfolg, ohne den Zustand zu überprüfen. Siehe docs/SECURITY.md.

Lizenz

MIT