mcp-discord

Name: MCP Discord
Author: goul4rt

El servidor MCP de código abierto más completo para Discord.

License: MIT Node.js TypeScript GitHub stars

Dale a cualquier cliente MCP (Claude, Cursor, agentes personalizados) control total sobre Discord: mensajes, moderación, canales, roles y más. Nacido del uso en producción en delfus.app, de código abierto para la comunidad.

Portugues (BR)

¿Por qué mcp-discord?

Más de 30 herramientas en 8 categorías: servidores, canales, mensajes, reacciones, miembros, roles, moderación y monitoreo
Modo dual: ejecútalo de forma independiente (proceso propio) o intégralo como plugin en tu bot de discord.js existente
Solo REST o Gateway: elige entre el modo ligero solo REST o el gateway WebSocket completo para funciones en tiempo real
Dos transportes: stdio (predeterminado, para Claude Desktop / Claude Code) o HTTP con autenticación mediante token Bearer
Probado en producción: construido y utilizado en producción en delfus.app

Inicio rápido

Requisitos previos

Node.js 18 o superior
Un token de bot de Discord

Instalación

# Clone the repository
git clone https://github.com/goul4rt/mcp-discord.git
cd mcp-discord

# Install dependencies
npm install

# Build
npm run build

Configuración

cp .env.example .env

Edita .env y añade tu token de bot de Discord:

DISCORD_TOKEN=your-bot-token-here

Ejecución

# stdio transport (default — for MCP clients like Claude)
npm start

# HTTP transport (for remote/web clients)
npm run start:http

Configuración del cliente MCP

Claude Desktop / Claude Code

Añade esto a tu archivo de configuración MCP:

{
    "mcpServers": {
        "discord": {
            "command": "node",
            "args": ["dist/standalone.js"],
            "cwd": "/path/to/mcp-discord",
            "env": {
                "DISCORD_TOKEN": "your-bot-token-here"
            }
        }
    }
}

Con Gateway (funciones en tiempo real)

{
    "mcpServers": {
        "discord": {
            "command": "node",
            "args": ["dist/standalone.js"],
            "cwd": "/path/to/mcp-discord",
            "env": {
                "DISCORD_TOKEN": "your-bot-token-here",
                "DISCORD_USE_GATEWAY": "true"
            }
        }
    }
}

Herramientas

Servidor / Guild (2 herramientas)

Herramienta	Descripción
`list_servers`	Lista todos los servidores de Discord a los que tiene acceso el bot
`get_server_info`	Obtiene información detallada sobre un servidor específico

Canales (7 herramientas)

Herramienta	Descripción
`get_channels`	Lista todos los canales de un servidor
`get_channel`	Obtiene información detallada sobre un canal
`create_channel`	Crea canales de texto, voz, categoría, anuncios, foro o escenario
`edit_channel`	Edita el nombre del canal, tema, NSFW, modo lento, posición, categoría
`delete_channel`	Elimina permanentemente un canal
`create_thread`	Crea un hilo en un canal (opcionalmente a partir de un mensaje)
`archive_thread`	Archiva un hilo

Mensajes (8 herramientas)

Herramienta	Descripción
`send_message`	Envía mensajes con texto, embeds enriquecidos y respuestas
`read_messages`	Lee mensajes recientes con paginación (hasta 100)
`search_messages`	Busca mensajes por contenido, autor o canal
`edit_message`	Edita un mensaje del bot
`delete_message`	Elimina un solo mensaje
`delete_messages_bulk`	Elimina en masa de 2 a 100 mensajes (con menos de 14 días de antigüedad)
`pin_message`	Fija un mensaje
`unpin_message`	Desfija un mensaje

Reacciones (2 herramientas)

Herramienta	Descripción
`add_reaction`	Añade una reacción con emoji (Unicode o personalizado)
`remove_reaction`	Elimina una reacción

Miembros / Usuarios (4 herramientas)

Herramienta	Descripción
`list_members`	Lista los miembros del servidor con paginación
`get_member`	Obtiene información detallada del miembro (roles, apodo, fecha de unión)
`get_user`	Obtiene información sobre cualquier usuario de Discord por ID
`search_members`	Busca miembros por nombre de usuario o apodo

Roles (4 herramientas)

Herramienta	Descripción
`list_roles`	Lista todos los roles con permisos, colores y recuento de miembros
`create_role`	Crea un nuevo rol
`add_role`	Añade un rol a un miembro
`remove_role`	Elimina un rol de un miembro

Moderación (4 herramientas)

Herramienta	Descripción
`timeout_user`	Silencia temporalmente a un usuario (hasta 28 días)
`kick_user`	Expulsa a un usuario del servidor
`ban_user`	Banea a un usuario con eliminación opcional de mensajes
`unban_user`	Desbanea a un usuario

Monitoreo (2 herramientas)

Herramienta	Descripción
`get_audit_log`	Ve el registro de auditoría del servidor (baneos, expulsiones, cambios)
`check_mentions`	Encuentra menciones recientes (@) del bot o de un usuario

Arquitectura

┌─────────────────────────────────────────────────┐
│                  MCP Client                      │
│          (Claude, Cursor, custom)                │
└──────────────────┬──────────────────────────────┘
                   │ stdio or HTTP
┌──────────────────▼──────────────────────────────┐
│               MCP Server                         │
│         (transport + tool routing)                │
└──────────────────┬──────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────┐
│            Tool Registry                         │
│         (30 tools, Zod validation)               │
└──────────────────┬──────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────┐
│          DiscordProvider (interface)              │
├─────────────────────┬───────────────────────────┤
│ StandaloneProvider  │  IntegratedProvider        │
│ (own token + REST/  │  (uses host bot's          │
│  optional gateway)  │   existing connection)      │
└─────────────────────┴───────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────┐
│              Discord API                         │
└─────────────────────────────────────────────────┘

Abstracción del proveedor: Las herramientas MCP nunca tocan discord.js directamente. Llaman a la interfaz DiscordProvider, que tiene dos implementaciones:

StandaloneProvider: crea su propia conexión usando un token de bot. Prioriza REST con gateway opcional. Úsalo cuando se ejecute como un proceso separado.
IntegratedProvider: recibe un Client de discord.js existente del bot anfitrión. Sin sobrecarga, caché y gateway compartidos. Úsalo cuando se integre en un bot existente.

Guía de integración

Para usar mcp-discord como un plugin dentro de tu bot de discord.js existente:

import { IntegratedProvider, createMcpServer } from 'mcp-discord';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

// Your existing discord.js client
const provider = new IntegratedProvider({ client: myDiscordClient });
await provider.connect();

const server = createMcpServer({ provider });
const transport = new StdioServerTransport();
await server.connect(transport);

El IntegratedProvider utiliza la conexión de gateway existente de tu bot: sin WebSocket adicional, sin autenticación extra, sin memoria adicional.

Referencia de configuración

Variable	Requerido	Predeterminado	Descripción
`DISCORD_TOKEN`	Sí	—	Token del bot de Discord
`DISCORD_USE_GATEWAY`	No	`false`	Conectar al gateway WebSocket de Discord para funciones en tiempo real
`MCP_TRANSPORT`	No	`stdio`	Modo de transporte: `stdio` o `http`
`MCP_PORT`	No	`3100`	Puerto del servidor HTTP (solo cuando `MCP_TRANSPORT=http`)
`MCP_AUTH_TOKEN`	No	—	Token Bearer para autenticación de transporte HTTP

Contribución

¡Las contribuciones son bienvenidas! Consulta CONTRIBUTING.md para la configuración de desarrollo, estilo de código y cómo añadir nuevas herramientas.

Licencia

MIT

Autor

Creado por @goul4rt. Nacido de delfus.app, de código abierto para la comunidad.

MCP Discord