mcp-discord
The most complete open-source MCP server for Discord.
接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令? 兩種安裝方式的差異
Give any MCP client (Claude, Cursor, custom agents) full control over Discord — messages, moderation, channels, roles, and more. Born from production use at delfus.app, open-sourced for the community.
Install via npm:
npm install @goul4rt/mcp-discord
Add to your MCP config (usually ~/Library/Application\ Support/Claude/claude_desktop_config.json on Mac):
{
"mcpServers": {
"discord": {
"command": "node",
"args": ["-e", "require('@goul4rt/mcp-discord').runStandalone()"],
"env": {
"DISCORD_TOKEN": "your-bot-token-here"
}
}
}
}
Restart Claude, then ask:
"List all Discord servers I have access to"
Claude will automatically invoke the list_servers tool and show you the results.
To enable real-time Discord gateway features (like monitoring new messages as they arrive), add this to your config:
{
"mcpServers": {
"discord": {
"command": "node",
"args": ["-e", "require('@goul4rt/mcp-discord').runStandalone()"],
"env": {
"DISCORD_TOKEN": "your-bot-token-here",
"DISCORD_USE_GATEWAY": "true"
}
}
}
}
# Clone the repository
git clone https://github.com/goul4rt/mcp-discord.git
cd mcp-discord
# Install dependencies
npm install
# Build
npm run build
Copy the example environment file:
cp .env.example .env
Edit .env and add your Discord bot token:
DISCORD_TOKEN=your-bot-token-here
Run the MCP server as a separate process (stdio transport):
npm start
Or HTTP transport (for remote clients):
npm run start:http
Use IntegratedProvider to embed mcp-discord into your existing discord.js bot:
import { IntegratedProvider, createMcpServer } from '@goul4rt/mcp-discord';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
const provider = new IntegratedProvider({ client: myDiscordClient });
await provider.connect();
const server = createMcpServer({ provider });
const transport = new StdioServerTransport();
await server.connect(transport);
Ask Claude naturally — it will automatically invoke the right tool:
Example 1: Send a message
> "Send a message to the #general channel saying 'Hello everyone!'"
Claude invokes: `send_message` with `channelId`, `content`
Example 2: Search for a member
> "Find all members in my server with 'admin' in their username"
Claude invokes: `search_members` with `username` filter
Example 3: Moderate a user
> "Timeout the user @Spam for 24 hours with reason 'Spam'"
Claude invokes: `timeout_user` with userId, duration, reason
Example 4: View audit log
> "Show me the last 10 bans in the server"
Claude invokes: `get_audit_log` with action filter
Use these examples as a starting point for your own MCP server or bot integration:
Example 1: Send a message
import { IntegratedProvider } from '@goul4rt/mcp-discord';
const provider = new IntegratedProvider({ client: myBot });
await provider.connect();
const result = await provider.sendMessage(channelId, {
content: 'Hello @members! New announcement:',
embeds: [{ title: 'Update', description: 'System online' }]
});
Example 2: Search members
const members = await provider.searchMembers(serverId, {
username: 'admin'
});
console.log(\`Found \${members.length} members matching search\`);
members.forEach(m => console.log(\`\${m.user.username} - roles: \${m.roles.length}\`));
Example 3: Moderate a user
await provider.timeoutUser(serverId, userId, {
duration: 24 * 60 * 60 * 1000, // 24 hours in ms
reason: 'Spam',
moderatorId: botId
});
Example 4: Fetch audit log
const auditLog = await provider.getAuditLog(serverId, {
limit: 10,
actionType: 'BAN' // Filter by specific action
});
auditLog.entries.forEach(entry => {
console.log(\`\${entry.action}: \${entry.targetId} by \${entry.executorId}\`);
});
Example 5: Create a role
const newRole = await provider.createRole(serverId, {
name: 'Muted',
color: 0xFF0000, // Red
mentionable: false
});
console.log(\`Created role: \${newRole.name}\`);
Example 6: Create a thread
const thread = await provider.createThread(channelId, {
name: 'Bug: Login fails on Safari',
messageId: originalMessageId,
autoArchiveDuration: 1440 // 1 day
});
Example 7: List all roles
const roles = await provider.listRoles(serverId);
roles.forEach(role => {
console.log(\`\${role.name} - members: \${role.memberCount}\`);
});
Example 8: Add a reaction
await provider.addReaction(channelId, messageId, {
emoji: '👍' // Unicode emoji
});
// Or custom emoji:
await provider.addReaction(channelId, messageId, {
emoji: '<:myemoji:123456789>'
});
Symptoms: "Invalid token" error or 401 Unauthorized from Discord API
Solution:
.env file has exact format: DISCORD_TOKEN=token-here (no quotes)Symptoms: Claude says "I don't have access to Discord tools" or tools don't appear
Solution:
npm start should show "MCP server listening"npm run start:http should show "HTTP server on port 3100"~/Library/Application\ Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.jsonnode command is available in your PATH (type node --version in terminal)Symptoms: When using DISCORD_USE_GATEWAY=true, connection hangs or times out
Solution:
# Test connectivity to Discord gateway
curl -I https://gateway.discord.gg
DISCORD_USE_GATEWAY=false) to isolate the issueSymptoms: Tool executes but fails with "Missing Permissions: SEND_MESSAGES" (or similar)
Solution:
┌─────────────────────────────────────────────────┐
│ MCP Client │
│ (Claude, Cursor, custom) │
└──────────────────┬──────────────────────────────┘
│ stdio or HTTP
┌──────────────────▼──────────────────────────────┐
│ MCP Server │
│ (transport + tool routing) │
└──────────────────┬──────────────────────────────┘
│
┌──────────────────▼──────────────────────────────┐
│ Tool Registry │
│ (80+ tools, Zod validation) │
└──────────────────┬──────────────────────────────┘
│
┌──────────────────▼──────────────────────────────┐
│ DiscordProvider (interface) │
├─────────────────────┬───────────────────────────┤
│ StandaloneProvider │ IntegratedProvider │
│ (own token + REST/ │ (uses host bot's │
│ optional gateway) │ existing connection) │
└─────────────────────┴───────────────────────────┘
│
┌──────────────────▼──────────────────────────────┐
│ Discord API │
└─────────────────────────────────────────────────┘
Provider abstraction: MCP tools never touch discord.js directly. They call the DiscordProvider interface, which has two implementations:
Client from the host bot. Zero overhead, shared cache and gateway. Use when embedding in an existing bot.To use mcp-discord as a plugin inside your existing discord.js bot:
import { IntegratedProvider, createMcpServer } from '@goul4rt/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);
The IntegratedProvider uses your bot's existing gateway connection — no extra WebSocket, no extra authentication, no extra memory.
Contributions are welcome! See CONTRIBUTING.md for development setup, code style, and how to add new tools.
Created by @goul4rt. Born from delfus.app, open-sourced for the community.
The most complete open-source MCP server for Discord — 80+ tools, dual-mode: integrated (plugin) or standalone
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
MCP Discord 透過 stdio 在本機執行。
上次檢查時間:2026-10-28。 The most complete open-source MCP server for Discord — 80+ tools, dual-mode: integrated (plugin) or standalone