Skip to main content
Glama

Discord Agent

一个驻留在 Discord 中的自主 AI 智能体。提及它,用自然语言向它提问,它就会检查服务器、规划多步操作、通过 Discord API 工具执行操作、验证结果,然后向你汇报——就像真正的管理员一样。

它天生支持多服务器:每个操作都严格限定在发起该操作的服务器内,绝无可能跨服务器混淆上下文、记忆或权限。

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.

功能特性

  • 自主规划与执行 — 用户描述的是目标,而非 API 调用。

  • 不限定 LLM — 支持 OpenAI、Anthropic、Gemini、OpenRouter、DeepSeek、Ollama 或任何兼容 OpenAI 的端点。

  • 多服务器隔离 — 每个查询、缓存条目和记忆记录都按服务器进行命名空间隔离。

  • 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.*。

  • 权限智能 — 解释成员为什么可以或不可以执行操作。

  • 安全门控 — 风险分级、可配置的确认级别、试运行/计划模式、幂等的 ensure_* 操作、独立于 LLM 的授权机制。

  • 抗提示注入 — 所有 Discord 内容均被视为不可信;规则和服务器边界不可被覆盖。

  • 服务器范围的记忆 — “记住……”、“忘记……”、“你记得什么?”

  • 事件自动化与定时任务 — 欢迎消息、表情回应、每周总结。

  • 审计追踪 — 每个服务器的结构化运行/操作历史。

  • CLI 诊断 — agent doctor、agent status、agent guilds、agent capabilities、agent test。

Related MCP server: discord-mcp

快速开始

1. 创建 Discord 应用

  1. 前往 https://discord.com/developers/applications 并创建一个新应用。

  2. 在 Bot 下创建一个机器人并复制令牌。

  3. 启用所需的特权网关意图:

    • Server Members Intent

    • Message Content Intent

  4. 使用 OAuth2 → URL 生成器,以 bot 范围及其所需的权限(例如 Manage Channels、Manage Roles、Manage Messages)邀请机器人。机器人只会执行其 Discord 权限允许的操作。

2. 配置

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. 运行

Docker:

docker compose up --build

本地开发:

npm install
npm run dev

生产构建:

npm run build
npm start

4. 使用

在任何频道中提及机器人:

@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

在请求前加上 plan / preview / dry-run 前缀,可在不执行的情况下获取计划;加上 audit / analyze 前缀则可进行只读分析。

命令与诊断

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

项目附带一个多阶段 Dockerfile(在完整工具链镜像中构建,以 node 用户在精简镜像中运行)和一个 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

SQLite 数据库持久化在 agent-data 卷的 /app/data/agent.sqlite 中。参见 docs/DEPLOYMENT.md。

预构建镜像由 Docker 工作流 在每次推送到 main 分支及每个标签时发布到 GitHub Container Registry:

docker pull ghcr.io/NacreousDawn596/DiscordMCP:main

CI 工作流 在每次推送和 PR 上运行类型检查、测试套件和生产构建。

配置

完整列表参见 .env.example。关键设置:

变量

描述

DISCORD_BOT_TOKEN

机器人令牌(必填)。

LLM_PROVIDER

openai、anthropic、gemini、openrouter、ollama、deepseek、custom。

LLM_API_KEY / LLM_MODEL / LLM_BASE_URL

模型选择与端点(LLM_MODEL 接受逗号分隔的回退列表)。

AGENT_CONFIRMATION_LEVEL

需要确认的风险阈值(默认 HIGH)。

ENABLE_MODERATION

门控破坏性管理工具。

ALLOWED_USER_IDS

逗号分隔的用户 ID,可绕过服务器级授权。

连接到 OpenCode(MCP)

是的 — discord.* 工具套件可以通过 stdio 作为真正的 Model Context Protocol 服务器暴露给 opencode(或任何 MCP 客户端:Claude Code、Cursor 等)。连接后,你可以通过如下提示词来操控你的 Discord 服务器:

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

工作原理

MCP 服务器(npm run mcp)启动同一个 Discord 机器人,使用你的令牌登录,并通过 stdin/stdout 提供全部 127 个工具。每个工具都接受可选的 guild_id 参数,因此同一个服务器可以管理机器人所在的每个服务器。

重要提示: MCP 调用以机器人自身(管理员上下文)的身份运行,范围仅限于机器人实际能执行的操作。破坏性管理操作(封禁/踢出/清除)仍需要 ENABLE_MODERATION=true。MCP 没有交互式确认通道,因此操作会立即执行。

第 1 步 — 构建(或使用 tsx 运行)

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

第 2 步 — 配置 opencode

在你的 opencode 配置中添加一个 mcp 条目。这可以是项目配置(opencode.json)或全局配置(~/.config/opencode/opencode.json)。

选项 A — 依赖项目的 .env(推荐):

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

将 cwd 设置为项目目录,以便服务器加载你的 .env(其中包含 DISCORD_BOT_TOKEN,以及可选的 MCP_DEFAULT_GUILD_ID)。

选项 B — 显式传递令牌(无需 .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
    }
  }
}

将 timeout 设置为高于默认的 5 秒 — 服务器在应答前需要将机器人登录到 Discord,这可能需要几秒钟。

开发模式(不构建): 使用 "command": ["npx", "tsx", "src/mcp/entry.ts"]。

第 3 步 — 重启 opencode

重启 opencode,以便它加载新的 MCP 服务器。你可以通过 /mcp 验证连接(或直接询问:list the discord-agent tools)。

第 4 步 — 使用

每个工具都以 discord_ 为前缀。示例:

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

如果设置了 MCP_DEFAULT_GUILD_ID(或机器人只在一个服务器中),你可以省略 guild_id:

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

MCP 选项

选项

用途

MCP_DEFAULT_GUILD_ID

当工具调用省略 guild_id 时的默认服务器。

guild_id(工具参数)

特定调用所针对的服务器;覆盖默认值。

完整的工具目录参见 docs/CONFIGURATION.md,实时列表参见 npm run cli -- capabilities。

架构

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

详细信息参见 docs/ARCHITECTURE.md、docs/CONFIGURATION.md、docs/SECURITY.md 和 docs/DEPLOYMENT.md。现成的示例提示词和提供商配置参见 examples/。

测试

npm test

单元测试覆盖服务器隔离、授权、权限计算、风险分级、记忆隔离、工具验证、计划验证和提示注入防御。

安全

机器人具有不可变更的边界:它绝不暴露自己的令牌,绝不绕过 Discord 权限,绝不跨越服务器边界,绝不让消息内容覆盖策略,绝不为未授权用户授权特权操作,并且绝不在未验证状态的情况下声称成功。参见 docs/SECURITY.md。

许可证

MIT

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI clients to manage Discord servers through natural language, offering tools for guilds, channels, messages, roles, members, webhooks, invites, and automations. Includes a conversational agent that responds to @mentions in Discord.
    10
    Apache 2.0
  • A
    license
    Not graded
    quality
    F
    maintenance
    Control your Discord server with AI. Lets you manage channels, roles, members, messages, and more through natural language.
    153 npm
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables managing a Discord server using natural language through AI clients like Claude, with 139 admin tools across 20 categories for roles, channels, members, messages, threads, moderation, and more.
    170 npm
    39
    MIT
  • A
    license
    B
    quality
    A
    maintenance
    Gives your AI assistant full control of a Discord server: 148 tools for chat, moderation, automod, events, and administration, up to building a complete community server from one paragraph. Every destructive action previews first and waits for your confirmation.
    155
    130 npm
    11
    Elastic 2.0