AI导哈

Discord MCP服务器

一个基于Model Context Protocol (MCP)的服务器，使AI代理能够通过Discord REST API v9与Discord交互，提供发送消息、读取频道历史、管理服务器等功能。

  • by NickyHeC
  • Python
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 NickyHeC/discord-mcp

使用说明

断开MCP服务器

模型上下文协议（MCP）服务器，使AI代理能够使用Discord REST API v9与Discord交互。该服务器采用Dedalus MCP框架构建，提供用于发送消息、读取频道历史、管理服务器等的工具。所有API调用都使用Dedalus MCP ctx.dispatch 自动身份验证处理机制。

先决条件

  • Python 3.10或更高版本
  • Discord应用程序和机器人令牌
  • 对Discord机器人设置的基本了解

Discord Bot设置

在使用此MCP服务器之前，您需要创建一个Discord应用程序并配置一个机器人。请参阅官方的Discord Developer文档：

快速设置步骤

  1. 创建Discord应用程序

  2. 创建和配置您的Bot

    • 点击“添加机器人”或“重置令牌”以生成机器人令牌
    • 安全地保存您的机器人令牌 -你需要它 .env 文件

  3. 启用特权网关意图 ⚠️ 重要

    在 机器人 选项卡，在“特权网关意图”下，您 必须 启用以下意图：

    • ✅ 存在意图 -接收状态更新事件所需
    • ✅ 服务器成员意图 -接收GUILD_MEMBERS事件所需
    • ✅ 消息内容意图 -在大多数消息中接收消息内容所必需的

    注： 一旦你的机器人达到100台或更多服务器，这些意图将需要Discord的验证和批准。

  4. 配置授权流 （可选）

    • 公共机器人：如果您希望其他人能够将您的机器人添加到他们的服务器上，请启用
    • 需要OAuth2代码授权：如果您的应用程序需要多个作用域，请启用

  5. 邀请您的机器人到服务器

    • 首选 OAuth2>URL生成器
    • 选择 bot 范围
    • 重要：选择以下权限：
      • ✅ 查看频道 -需要 list_channels 工具
      • ✅ 发送消息 -需要 send_message 工具
      • ✅ 读取消息历史记录 -需要 read_messages 工具
      • ✅ 管理邮件 -需要 delete_message 工具
      • ✅ 添加反应 -需要 add_reaction 工具
    • 复制生成的URL并邀请机器人到您的服务器
    • 备注：工具描述中提到了OAuth2作用域，如 guilds.channels.read，但对于bot令牌，这些是通过bot权限处理的。确保机器人具有上面列出的所需权限。

安装

  1. 克隆存储库：

    git clone <repository-url>
cd discord-mcp

  2. 安装依赖项 （可编辑安装，模式与 mcp模板 API重点项目）：

    pip install -e .

    或者： uv pip install -e .

  3. 环境变量

    cp .env.example .env

    集 DISCORD_TOKEN 用于本地运行和测试。在Dedalus上，秘密名称必须匹配 SecretKeys(token="DISCORD_TOKEN") 在 src/main.py。参见 .env.example 对于可选的Dedalus URL和 PORT / HOST.

运行服务器

启动MCP服务器：

python -m src.main

或者控制台脚本： discord-mcp

服务器正在监听 PORT （默认值 8080)以及 HOST （默认值 0.0.0.0).

可用工具

Discord MCP服务器提供以下工具：

  • send_message -向Discord频道发送消息。长度超过2000个字符的消息会自动拆分为多条消息。
  • read_messages -从频道读取最近的消息（需要 messages.read 范围）。返回一个字典 count, messages （消息字典列表），可选 error 现场。
  • list_servers -列出机器人所在的所有Discord服务器。返回服务器字典列表 id, name, icon, owner，以及 permissions.
  • get_server_info -获取有关Discord服务器的详细信息。返回一个包含服务器详细信息的字典，包括 id, name, description, member_count, features等等。
  • list_channels -列出服务器中的所有频道（需要 guilds.channels.read 范围）。返回一个字典 count, channels （频道字典列表），可选 error 现场。
  • add_reaction -在消息中添加反应表情符号
  • delete_message -从频道中删除消息
  • get_user_info -获取有关Discord用户的信息。返回一个包含用户详细信息的字典，包括 id, username, discriminator, global_name, bot，以及 avatar_url.
  • list_members -列出服务器中的成员（需要 guilds.members.read 范围）。返回一个字典 count, members （成员字典列表），可选 error 现场。
  • discord_smoke -烟雾测试工具，通过调用验证Discord身份验证 /users/@me.退货 success, error，以及 body 领域。

响应格式

所有工具都返回扁平的JSON可序列化字典（没有嵌套的Pydantic模型），以确保与托管的MCP服务器的兼容性。可能失败的读取操作包括可选操作 error 响应中的字段用于优雅的错误处理。

配置

环境变量

变量 描述 必填 来源
DISCORD_TOKEN 您的Discord机器人令牌 是 通过连接机制从Dedalus作为秘密传递
PORT MCP服务器的端口（默认：8080） 否 本地 .env 文件或环境
DEDALUS_AS_URL 授权服务器URL（默认值：https://as.dedaluslabs.ai) 否 环境变量

重要:

  • DISCORD_TOKEN 在部署到托管的MCP服务器时，必须作为机密从Dedalus传递。
  • Connection定义需要具有确切名称的密钥： DISCORD_TOKEN.
  • 身份验证通过Dedalus MCP自动处理 ctx.dispatch 机制-令牌由框架根据Connection定义注入。
  • 连接名称为 "discord" 并使用 auth_header_format="Bot {api_key}" 用于Discord API身份验证。

频道权限

确保你的机器人在你想使用它的频道中拥有必要的权限：

  • 查看频道 -需要查看频道
  • 发送消息 -需要发送消息
  • 读取消息历史记录 -需要阅读消息
  • 管理邮件 -需要删除邮件
  • 添加反应 -需要添加反应

特性

自动消息分块

这 send_message 该工具通过将长消息拆分为多条消息来自动处理Discord的2000个字符限制。这在发送长篇议程或格式化内容时特别有用。

  • 如果可能的话，消息会在行边界上拆分
  • 如果需要，很长的线很难分开
  • 每个块都作为单独的消息发送
  • 该工具返回最后发送的消息的ID

平面JSON模式

所有工具都返回扁平的JSON可序列化字典，以确保与托管的MCP服务器的兼容性，并避免模式验证问题。这意味着：

  • 响应中没有嵌套的Pydantic模型
  • 所有值都是JSON基元（str、int、bool、list、dict）
  • 可选字段被省略，而不是设置为null
  • 错误信息包含在可选的 error 领域

Dedalus MCP集成

此服务器使用Dedalus MCP框架，并遵循推荐的模式：

  • 基于连接的身份验证：用途 Connection 定义与 name="discord" 和 auth_header_format="Bot {api_key}"
  • 基于调度的API调用：所有Discord API调用都使用 ctx.dispatch("discord", HttpRequest(...)) 而不是直接的HTTP库
  • 自动代币注入：框架自动从Connection定义中注入令牌
  • 服务器配置: authorization_server, streamable_http_stateless=True，以及 http_security=TransportSecuritySettings(enable_dns_rebinding_protection=False) （与Dedalus MCP API密钥模板一致）
  • 模块级工具集合：在模块级别收集工具，以确保在部署验证期间服务器准备就绪

增强的错误处理

  • 带有特定Discord错误代码的详细错误消息
  • 用于调试的完整错误响应日志记录
  • 读取操作中的优雅错误处理（响应中返回的错误，未引发）
  • 常见错误的具体处理（400、401、403、404、429）

测试

1.连接+令牌（无服务器） -与mcp-template API密钥相同的模式 client.py:

python -m src.client --test-connection

需要 DISCORD_TOKEN 在环境中（例如来自 .env).呼叫Discord GET /users/@me 通过 ConnectionTester.

2.运行服务器+MCP客户端

python -m src.main   # terminal 1
python -m src.client # terminal 2 (default URL `http://127.0.0.1:8080/mcp`)

3.可选：烟雾脚本 — python scripts/test_deploy.py 启动服务器，探测 /mcp，并运行客户端。

您还可以从Python调用工具函数（用于即席调试）：

import asyncio
from src.tools import send_message, read_messages, list_channels

# Test sending a message
asyncio.run(send_message("channel_id", "Hello, Discord!"))

# Test reading messages
asyncio.run(read_messages("channel_id", limit=10))

# Test listing channels
asyncio.run(list_channels("server_id"))

项目结构

discord-mcp/
├── src/
│   ├── main.py          # MCPServer, Connection (API key / bot token), tool collection
│   ├── tools.py         # @tool definitions
│   ├── discord_api.py   # Discord REST v9 via ctx.dispatch("discord", ...)
│   └── client.py        # --test-connection and MCPClient smoke tests
├── scripts/
│   └── test_deploy.py   # Optional local deploy smoke (server + /mcp + client)
├── .env.example         # Copy to .env for local dev
├── pyproject.toml       # Dependencies and hatchling package layout
├── API_V9.md
├── AUTHENTICATION.md
└── README.md

关键文件

  • src/main.py：定义 MCPServer, Connection （name=“discord”），并在模块级别收集所有工具
  • src/tools.py：包含所有用以下装饰的Discord交互工具 @tool
  • src/discord_api.py：使用的低级Discord API函数 ctx.dispatch("discord", ...) 用于经过身份验证的请求

故障排除

常见问题

  1. 403禁止/丢失访问（特别是 list_channels)

    • 用于托管MCP服务器：确保机器人令牌在被邀请到服务器时具有所需的权限
    • 检查机器人角色在服务器中是否具有“查看频道”权限
    • 转到服务器设置>角色>[您的机器人角色]，验证是否启用了“查看频道”
    • 如果机器人在没有适当权限的情况下被邀请，请使用所有必需的权限重新邀请它（请参阅Discord bot Setup中的步骤5）
    • 适用于dedaluslabs.ai上的托管服务器：验证 DISCORD_TOKEN 在服务器的环境变量中正确配置
    • 错误响应将包括有关缺少哪些权限的详细信息

  2. 401未经授权

    • 验证 DISCORD_TOKEN 正确且未过期
    • 检查您的令牌周围是否没有多余的空格或引号 .env 文件
    • 对于托管的MCP服务器，确保令牌通过连接/秘密值机制正确传递
    • 如果需要，在Discord开发者门户中重新生成令牌

  3. 消息太长（400/表单正文无效）

    • Discord每条消息的长度限制为2000个字符
    • 这 send_message 该工具会自动将长度超过2000个字符的消息拆分为多条消息
    • 如果您仍然看到此错误，请查看错误消息以了解错误的详细信息
    • 错误响应现在包括完整的验证详细信息，以便于调试

  4. 读取托管MCP服务器中的工具返回错误字段

    • 所有阅读工具(list_channels, read_messages, list_members等）可以返回 error 响应中的字段
    • 这通常表示权限问题（403）或身份验证问题（401）
    • 检查 error 响应字典中的字段以获取具体详细信息
    • 验证机器人在目标服务器中是否具有所需的权限
    • 确保bot令牌有效，并在托管环境中正确配置
    • 代理商应检查 error 在响应中输入字段，并优雅地处理错误

  5. SSL证书错误

    • 服务器使用Dedalus MCP的调度机制，自动处理SSL
    • 不需要额外的SSL配置

  6. 意图不起作用

    • 确保您已在Discord开发人员门户中启用了所需的特权网关意图
    • 启用意图后重新启动机器人

  7. 速率限制（429）

    • 如果您发送的消息太多太快，Discord可能会限制请求的速率
    • 错误消息将包括重试定时信息
    • 在处理429错误时，在代理中实现退避逻辑

托管MCP服务器问题

在托管平台（例如dedaluslats.ai）上使用此MCP服务器时：

  1. 凭据配置

    • DISCORD_TOKEN 必须通过连接机制作为秘密从Dedalus传递
    • 中的连接定义 main.py 需要带名称的秘密 "DISCORD_TOKEN"
    • 身份验证通过以下方式自动处理 ctx.dispatch -无需手动访问令牌
    • 验证令牌是否过期或无效
    • 使用 discord_smoke 测试身份验证的工具

  2. 权限错误

    • 托管服务器使用相同的机器人令牌，因此在邀请机器人时必须授予权限
    • 如果 list_channels 403失败，机器人需要服务器中的“查看频道”权限
    • 如果需要，以适当的权限重新邀请机器人

  3. 错误可见性

    • 所有读取工具在 error 他们回应的领域
    • 代理商应检查 response.get("error") 查看详细的错误消息
    • 错误消息包括如何修复权限问题的具体指导
    • 记录完整的错误响应以进行调试（有关详细信息，请查看服务器日志）

  4. 消息分块

    • 长消息（>2000个字符）会自动拆分为多条消息
    • 每个块都作为单独的消息发送
    • 该工具返回最后发送的消息的ID
    • 这可以防止400个消息长度违规错误

API文档

此服务器使用Discord REST API版本9。有关API的详细文档，请参阅：

许可证

MIT许可证-请参阅 许可证 详细信息文件

贡献

欢迎投稿！请随时提交拉取请求。

支持

关于以下问题：

重要提示： 别忘了启用 特权网关意图 如Discord开发者门户所示，在您的Discord机器人设置中设置（存在意图、服务器成员意图和消息内容意图）！

相关 MCP