Discord Agent

Un agente de IA autónomo que vive dentro de Discord. Menciónalo, pídele algo en lenguaje natural, e inspecciona el servidor, planifica acciones de varios pasos, las ejecuta a través de las herramientas de la API de Discord, verifica el resultado y responde, como haría un administrador real.

Está diseñado para múltiples servidores (multi-guild): cada operación está estrictamente limitada al servidor donde se invocó, sin posibilidad de mezclar contexto, memoria o permisos entre servidores.

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.

Características

• Planificación y ejecución autónomas — los usuarios describen objetivos, no llamadas a la API.

• Independiente del LLM — OpenAI, Anthropic, Gemini, OpenRouter, DeepSeek, Ollama o cualquier endpoint compatible con OpenAI.

• Aislamiento multiservidor — cada consulta, entrada de caché y registro de memoria tiene un espacio de nombres por servidor.

• Capa de herramientas estilo MCP — 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.*.

• Inteligencia de permisos — explica por qué un miembro puede o no actuar.

• Puertas de seguridad — clasificación de riesgo, niveles de confirmación configurables, modo dry-run/plan, operaciones ensure_* idempotentes, autorización independiente del LLM.

• Resistencia a la inyección de prompts — todo el contenido de Discord se trata como no confiable; las reglas y los límites entre servidores no se pueden anular.

• Memoria limitada al servidor — «recuerda que …», «olvida que …», «¿qué recuerdas?».

• Automatizaciones de eventos y tareas programadas — mensajes de bienvenida, reacciones, resúmenes semanales.

• Registro de auditoría — historial estructurado de ejecuciones/acciones por servidor.

• Diagnósticos CLI — agent doctor, agent status, agent guilds, agent capabilities, agent test.

Related MCP server: discord-mcp

Inicio rápido

1. Crea una aplicación de Discord

1. Ve a https://discord.com/developers/applications y crea una Nueva aplicación.

2. En Bot, crea un bot y copia el token.

3. Habilita los Privileged Gateway Intents necesarios:

   • Server Members Intent

   • Message Content Intent

4. Usa el OAuth2 → URL Generator para invitar al bot con el alcance bot y los permisos que necesite (por ejemplo, Manage Channels, Manage Roles, Manage Messages). El bot solo hará lo que sus permisos de Discord le permitan.

2. Configura

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

Docker:

docker compose up --build

Desarrollo local:

npm install
npm run dev

Compilación de producción:

npm run build
npm start

4. Úsalo

Menciona al bot en cualquier canal:

@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

Prefija una solicitud con plan / preview / dry-run para obtener un plan sin ejecutar, o con audit / analyze para un análisis de solo lectura.

Comandos y diagnósticos

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

El proyecto incluye un Dockerfile de varias etapas (compilación en una imagen completa con toolchain, ejecución en una imagen ligera como el usuario node) y un 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

La base de datos SQLite se persiste en el volumen agent-data en /app/data/agent.sqlite. Consulta docs/DEPLOYMENT.md.

Una imagen precompilada se publica en el GitHub Container Registry mediante el workflow de Docker en cada push a main y cada tag:

docker pull ghcr.io/NacreousDawn596/DiscordMCP:main

El workflow de CI ejecuta el typecheck, la suite de pruebas y una compilación de producción en cada push y PR.

Configuración

Consulta .env.example para ver la lista completa. Ajustes clave:

Conéctate a OpenCode (MCP)

Sí: la suite de herramientas discord.* se puede exponer a opencode (o a cualquier cliente MCP: Claude Code, Cursor, etc.) como un servidor real del Model Context Protocol a través de stdio. Cuando esté conectado, podrás manejar tu servidor de Discord con prompts como:

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

Cómo funciona

El servidor MCP (npm run mcp) inicia el mismo bot de Discord, inicia sesión con tu token y sirve las 127 herramientas a través de stdin/stdout. Cada herramienta acepta un guild_id opcional para que el mismo servidor pueda gestionar todos los servidores en los que esté el bot.

Importante: las llamadas MCP se ejecutan como el propio bot (contexto de administrador), limitadas a lo que el bot realmente puede hacer. La moderación destructiva (ban/kick/purge) sigue requiriendo ENABLE_MODERATION=true. No hay canal de confirmación interactiva a través de MCP, por lo que las acciones se ejecutan inmediatamente.

Paso 1 — Compila (o ejecuta con tsx)

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

Paso 2 — Configura opencode

Añade una entrada mcp a tu configuración de opencode. Puede ser la configuración del proyecto (opencode.json) o tu configuración global (~/.config/opencode/opencode.json).

Opción A — confía en el .env del proyecto (recomendada):

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

Establece cwd en el directorio del proyecto para que el servidor cargue tu .env (que contiene DISCORD_BOT_TOKEN y, opcionalmente, MCP_DEFAULT_GUILD_ID).

Opción B — pasa el token explícitamente (no se necesita .env):

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

Establece timeout por encima de los 5s por defecto: el servidor inicia sesión del bot en Discord antes de responder, lo que puede tardar unos segundos.

Dev (sin compilar): usa "command": ["npx", "tsx", "src/mcp/entry.ts"].

Paso 3 — Reinicia opencode

Reinicia opencode para que detecte el nuevo servidor MCP. Puedes verificar la conexión con /mcp (o preguntando: list the discord-agent tools).

Paso 4 — Úsalo

Cada herramienta tiene el prefijo discord_. Ejemplos:

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

Si MCP_DEFAULT_GUILD_ID está configurado (o el bot está en exactamente un servidor), puedes omitir guild_id:

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

Opciones de MCP

Consulta docs/CONFIGURATION.md para ver el catálogo completo de herramientas y npm run cli -- capabilities para la lista en vivo.

Arquitectura

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

Consulta docs/ARCHITECTURE.md, docs/CONFIGURATION.md, docs/SECURITY.md y docs/DEPLOYMENT.md para más detalles. Para ver ejemplos de prompts listos para usar y configuraciones de proveedores, consulta examples/.

Pruebas

npm test

Las pruebas unitarias cubren el aislamiento entre servidores, la autorización, el cálculo de permisos, la clasificación de riesgo, el aislamiento de memoria, la validación de herramientas, la validación de planes y las defensas contra la inyección de prompts.

Seguridad

El bot tiene límites inmutables: nunca expone su token, nunca omite los permisos de Discord, nunca cruza los límites entre servidores, nunca permite que el contenido de los mensajes anule las políticas, nunca autoriza acciones privilegiadas a usuarios no autorizados y nunca afirma éxito sin verificar el estado. Consulta docs/SECURITY.md.

Licencia

MIT