npm package: @fastmcp-me/discord-agent-mcp
Description: Production-ready Discord MCP Server
Latest version: 2.0.2

[![Add to Cursor](https://fastmcp.me/badges/cursor_dark.svg)](https://fastmcp.me/MCP/Details/1354/discord)
[![Add to VS Code](https://fastmcp.me/badges/vscode_dark.svg)](https://fastmcp.me/MCP/Details/1354/discord)
[![Add to Claude](https://fastmcp.me/badges/claude_dark.svg)](https://fastmcp.me/MCP/Details/1354/discord)
[![Add to ChatGPT](https://fastmcp.me/badges/chatgpt_dark.svg)](https://fastmcp.me/MCP/Details/1354/discord)
[![Add to Codex](https://fastmcp.me/badges/codex_dark.svg)](https://fastmcp.me/MCP/Details/1354/discord)
[![Add to Gemini](https://fastmcp.me/badges/gemini_dark.svg)](https://fastmcp.me/MCP/Details/1354/discord)

# Discord MCP Server

Production-ready Model Context Protocol (MCP) server for AI-assisted Discord management and automation. Provides 71 tools for comprehensive Discord API integration through the MCP protocol.

## Features

- **71 Discord Tools**: Complete API coverage for messaging, channels, threads, roles, members, moderation, emojis, stickers, scheduled events, auto-moderation, and application commands
- **MCP Protocol Compliant**: Full implementation of Model Context Protocol for AI assistant integration
- **Persistent Connection**: Robust Discord.js client with automatic reconnection
- **Production Ready**: TypeScript, comprehensive error handling, structured logging
- **Flexible Deployment**: Run locally, in Docker, or Kubernetes
- **Multiple Transports**: HTTP and stdio modes supported
- **Claude Code Native**: First-class integration with Anthropic's Claude Code CLI

## Table of Contents

- [Getting Started](#getting-started)
- [Discord Bot Setup](#discord-bot-setup)
- [Local Usage](#local-usage)
- [Claude Code Integration](#claude-code-integration)
- [Docker Deployment](#docker-deployment)
- [Kubernetes Deployment](#kubernetes-deployment)
- [Available Tools](#available-tools)
- [Configuration](#configuration)
- [Development](#development)
- [Troubleshooting](#troubleshooting)

## Getting Started

### Prerequisites

- **Node.js >= 20.0.0**
- **Discord Bot Token** - See [Discord Bot Setup](#discord-bot-setup)
- **npm or yarn** for dependency management

### Quick Clone and Run

```bash
# Clone the repository
git clone https://github.com/aj-geddes/discord-agent-mcp.git
cd discord-agent-mcp

# Install dependencies
npm install

# Create your configuration
cp .env.example .env
# Edit .env and add your DISCORD_TOKEN

# Build the project
npm run build

# Start the MCP server
npm start
```

The server will start on `http://localhost:3000` by default.

## Discord Bot Setup

Before using this MCP server, you need to create a Discord bot and invite it to your server.

### 1. Create a Discord Application

1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
2. Click **"New Application"** and give it a name
3. Navigate to the **"Bot"** section in the left sidebar
4. Click **"Add Bot"** and confirm

### 2. Get Your Bot Token

1. In the **Bot** section, click **"Reset Token"** to generate a new token
2. **Copy this token** - you'll need it for your `.env` file
3. ⚠️ **Never share this token publicly** - treat it like a password

### 3. Configure Bot Permissions

In the **Bot** section, enable these **Privileged Gateway Intents**:
- ✅ **Presence Intent** (optional - for member status)
- ✅ **Server Members Intent** (required - for member management)
- ✅ **Message Content Intent** (required - for reading messages)

### 4. Invite Bot to Your Server

1. Go to the **OAuth2 > URL Generator** section
2. Select scopes:
   - ✅ `bot`
   - ✅ `applications.commands`
3. Select bot permissions (or choose **Administrator** for full access):
   - Manage Channels
   - Manage Roles
   - Manage Messages
   - Read Messages/View Channels
   - Send Messages
   - Manage Threads
   - Moderate Members
4. Copy the generated URL and open it in your browser
5. Select your server and click **Authorize**

### 5. Configure Your Environment

```bash
# In your discord-agent-mcp directory
cp .env.example .env
```

Edit `.env` and add your token:
```bash
DISCORD_TOKEN=your_bot_token_here
TRANSPORT_MODE=http
HTTP_PORT=3000
LOG_LEVEL=info
LOG_FORMAT=json
```

## Local Usage

### Running the Server Locally

The MCP server can run directly on your machine without Docker or Kubernetes.

```bash
# Development mode (with auto-reload)
npm run dev

# Production mode
npm run build
npm start
```

The server will log its startup:
```
{"level":"info","message":"Starting Discord MCP Server","version":"2.0.0","transportMode":"http"}
{"level":"info","message":"Discord client connected successfully"}
{"level":"info","message":"MCP Server running on http://localhost:3000/mcp"}
```

### Testing the Server

```bash
# Health check
curl http://localhost:3000/health

# List available tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq
```

### Using with Any MCP Client

The server implements the standard MCP protocol and works with any MCP-compatible client:

```javascript
// Example: Using with MCP client library
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const client = new Client({
  name: "my-discord-client",
  version: "1.0.0"
});

await client.connect({
  url: "http://localhost:3000/mcp",
  transport: "http"
});

// List available tools
const tools = await client.listTools();

// Call a tool
const result = await client.callTool({
  name: "send_message",
  arguments: {
    channelId: "your-channel-id",
    content: "Hello from MCP!"
  }
});
```

## Claude Code Integration

### Setup with Claude Code CLI

1. **Start the MCP server locally:**
   ```bash
   npm start
   # Server runs at http://localhost:3000/mcp
   ```

2. **Add the server to Claude Code:**
   ```bash
   claude mcp add --transport http discord-agent http://localhost:3000/mcp
   ```

3. **Verify the connection:**
   ```bash
   claude mcp list
   # Should show: discord-agent: http://localhost:3000/mcp (HTTP)
   ```

4. **Use in Claude Code:**
   - Open Claude Code
   - Type `/mcp` to see available servers
   - All 71 Discord tools are now available with `mcp__discord-agent__` prefix

### Alternative: Project-Specific Configuration

Create `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "discord-agent": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}
```

### Example Usage in Claude Code

Once configured, you can use Discord tools directly in Claude Code conversations:

```
You: "Send a message to channel 123456789 saying 'Hello team!'"

Claude: I'll use the discord-agent MCP server to send that message.
[Uses mcp__discord-agent__send_message tool]

Claude: ✅ Message sent successfully to channel 123456789
```

```
You: "List all channels in the server"

Claude: Let me get the server channels for you.
[Uses mcp__discord-agent__list_channels tool]

Claude: Found 25 channels:
- 📢 announcements (text)
- 💬 general (text)
- 🗣️ voice-chat (voice)
...
```

## Docker Deployment

### Build and Run with Docker

```bash
# Build the image
docker build -t discord-mcp-server:latest .

# Run the container
docker run -d \
  --name discord-mcp \
  -p 3000:3000 \
  -e DISCORD_TOKEN=your_token_here \
  discord-mcp-server:latest

# Check logs
docker logs -f discord-mcp

# Stop the container
docker stop discord-mcp
```

### Using Docker Compose

Create `docker-compose.yml`:

```yaml
version: '3.8'
services:
  discord-mcp:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DISCORD_TOKEN=${DISCORD_TOKEN}
      - TRANSPORT_MODE=http
      - HTTP_PORT=3000
      - LOG_LEVEL=info
    restart: unless-stopped
```

Run with:
```bash
docker-compose up -d
```

## Kubernetes Deployment

### Prerequisites

- Kubernetes cluster (K3s, K3d, minikube, or cloud provider)
- `kubectl` configured

### Deploy to Kubernetes

1. **Build and load the image** (for local clusters like K3d):
   ```bash
   docker build -t discord-mcp-server:latest .
   k3d image import discord-mcp-server:latest -c your-cluster-name
   ```

2. **Create the secret with your bot token:**
   ```bash
   cp k8s/secret.yaml.example k8s/secret.yaml
   # Edit k8s/secret.yaml and replace YOUR_DISCORD_BOT_TOKEN_HERE
   ```

3. **Deploy to the cluster:**
   ```bash
   kubectl apply -f k8s/namespace.yaml
   kubectl apply -f k8s/secret.yaml
   kubectl apply -f k8s/configmap.yaml
   kubectl apply -f k8s/deployment.yaml
   kubectl apply -f k8s/service.yaml
   ```

4. **Verify the deployment:**
   ```bash
   kubectl get pods -n discord-agent-mcp
   kubectl logs -n discord-agent-mcp -l app=discord-mcp-server -f
   ```

5. **Access the server:**
   ```bash
   # Port-forward to localhost
   kubectl port-forward -n discord-agent-mcp svc/discord-mcp-server 3000:3000

   # Test the connection
   curl http://localhost:3000/health
   ```

## Available Tools (71)

### Messaging (10 tools)
- `send_message` - Send a text message to a channel
- `send_rich_message` - Send formatted embeds with images and styling
- `send_message_with_file` - Send a message with file attachments
- `read_messages` - Retrieve message history from a channel
- `edit_message` - Edit an existing message
- `delete_message` - Delete a specific message
- `bulk_delete_messages` - Delete multiple messages at once (up to 100)
- `add_reaction` - Add emoji reactions to messages
- `pin_message` - Pin important messages
- `unpin_message` - Unpin messages

### Channel Management (10 tools)
- `list_channels` - List all channels in a server
- `get_channel_details` - Get detailed channel information
- `create_text_channel` - Create a new text channel
- `create_voice_channel` - Create a new voice channel
- `create_category` - Create a category to organize channels
- `create_forum_channel` - Create a forum channel for discussions
- `create_stage_channel` - Create a stage channel for events
- `modify_channel` - Update channel settings (name, topic, slowmode)
- `delete_channel` - Delete a channel
- `set_channel_permissions` - Configure channel-specific permissions

### Thread Management (3 tools)
- `find_threads` - Search for threads in a forum by name
- `create_thread` - Create a new thread in a channel
- `archive_thread` - Archive and lock a thread

### Server Management (6 tools)
- `get_server_info` - Get detailed server information
- `modify_server` - Update server name, description, settings
- `get_audit_logs` - Retrieve audit log entries
- `list_webhooks` - List all webhooks in the server
- `create_webhook` - Create a new webhook
- `get_invites` - List active invite links
- `create_invite` - Create a new invite link

### Member Management (3 tools)
- `get_member_info` - Get detailed member information
- `list_members` - List all members with optional filters
- `set_nickname` - Change a member's server nickname

### Role Management (6 tools)
- `assign_role` - Add a role to a member
- `remove_role` - Remove a role from a member
- `create_role` - Create a new role with permissions
- `delete_role` - Delete a role
- `modify_role` - Update role settings and permissions
- `list_roles` - List all roles in the server
- `get_role_info` - Get detailed role information

### Moderation (5 tools)
- `kick_member` - Remove a member (they can rejoin)
- `ban_member` - Ban a member from the server
- `unban_member` - Remove a ban
- `timeout_member` - Temporarily mute a member
- `remove_timeout` - Remove a timeout from a member
- `get_bans` - List all banned users

### Emoji Management (4 tools) 🆕
- `list_guild_emojis` - Get all custom emojis for a guild
- `create_emoji` - Upload a custom emoji from base64 or file path
- `modify_emoji` - Update emoji name or role restrictions
- `delete_emoji` - Delete a custom emoji

### Sticker Management (4 tools) 🆕
- `list_guild_stickers` - Get all custom stickers for a guild
- `create_sticker` - Upload a custom sticker (PNG/APNG/Lottie)
- `modify_sticker` - Update sticker name, description, or tags
- `delete_sticker` - Delete a custom sticker

### Scheduled Events (6 tools)
- `list_scheduled_events` - Get all scheduled events for a guild
- `get_event_details` - Get detailed information about a specific event
- `create_scheduled_event` - Create Stage, Voice, or External events
- `modify_scheduled_event` - Update event properties and status
- `delete_scheduled_event` - Delete or cancel an event
- `get_event_users` - Get list of users interested in an event

### Auto-Moderation (5 tools) 🆕
- `list_automod_rules` - Get all auto-moderation rules for a guild
- `get_automod_rule` - Get detailed information about a specific rule
- `create_automod_rule` - Create keyword, spam, or mention filtering rules
- `modify_automod_rule` - Update rule settings, keywords, or actions
- `delete_automod_rule` - Delete an auto-moderation rule

### Application Commands (6 tools) 🆕
- `list_application_commands` - List all slash commands (guild or global)
- `get_application_command` - Get detailed command information
- `create_application_command` - Create slash commands or context menus
- `modify_application_command` - Update command properties
- `delete_application_command` - Delete a slash command
- `bulk_overwrite_commands` - Sync all commands at once

### Resources
- `discord://guilds` - List all guilds the bot is connected to

Note: Dynamic guild-specific resources (channels, roles, members) will be added in a future release when MCP SDK supports URI templates. Use the corresponding tools (list_channels, list_roles, list_members, etc.) to access guild-specific data.

### Prompts (8 total) 🆕
- `moderate-channel` - Interactive channel moderation assistant
- `create-announcement` - Step-by-step announcement creation guide
- `setup-server` - Interactive wizard for organizing new server structure
- `create-scheduled-event` - Guided event creation with timing and type selection
- `configure-automod-rule` - Auto-moderation rule setup (Phase 3 preview)
- `audit-permissions` - Security audit and permission analysis
- `setup-welcome-automation` - Configure welcome messages and auto-roles

## Configuration

### Environment Variables

Create a `.env` file (use `.env.example` as a template):

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `DISCORD_TOKEN` | **Yes** | - | Your Discord bot token |
| `TRANSPORT_MODE` | No | `http` | Transport mode: `http` or `stdio` |
| `HTTP_PORT` | No | `3000` | HTTP server port |
| `LOG_LEVEL` | No | `info` | Log level: `debug`, `info`, `warn`, `error` |
| `LOG_FORMAT` | No | `json` | Log format: `json` or `pretty` |

### Transport Modes

**HTTP Mode** (default):
- Server listens on HTTP port
- Suitable for remote connections
- Works with Claude Code HTTP transport
- Supports multiple concurrent clients

**Stdio Mode**:
- Communicates via stdin/stdout
- Suitable for local process integration
- Lower latency for local clients
- Single client only

## Development

### Project Structure

```
discord-agent-mcp/
├── src/
│   ├── server/          # MCP server implementation
│   │   ├── index.ts    # Main server entry point
│   │   └── config.ts   # Configuration management
│   ├── discord/         # Discord client management
│   │   └── client.ts   # Discord.js client wrapper
│   ├── tools/           # Discord tool implementations
│   │   ├── messaging.ts
│   │   ├── channels.ts
│   │   ├── members.ts
│   │   ├── roles.ts
│   │   ├── moderation.ts
│   │   └── server.ts
│   ├── resources/       # MCP resources
│   │   └── guilds.ts
│   ├── prompts/         # Interactive prompts
│   │   └── moderation.ts
│   ├── errors/          # Error definitions
│   ├── types/           # TypeScript types and schemas
│   └── utils/           # Utilities (logging, etc.)
├── k8s/                 # Kubernetes manifests
├── dist/                # Compiled JavaScript (generated)
├── .env.example         # Environment template
├── .mcp.json.example    # MCP config template
├── Dockerfile           # Container image definition
├── package.json         # Dependencies and scripts
└── tsconfig.json        # TypeScript configuration
```

### Building and Testing

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Development mode with auto-reload
npm run dev

# Run linting
npm run lint

# Run tests (if available)
npm test
```

### Adding New Tools

1. Create or modify a tool file in `src/tools/`
2. Use the `server.registerTool()` method
3. Define input/output schemas with Zod
4. Implement the tool logic
5. Rebuild and restart the server

Example:
```typescript
server.registerTool(
  "my_new_tool",
  {
    title: "My New Tool",
    description: "Does something useful",
    inputSchema: {
      param: z.string().describe("A parameter"),
    },
    outputSchema: {
      success: z.boolean(),
      result: z.string().optional(),
    },
  },
  async ({ param }) => {
    // Tool implementation
    return {
      content: [{ type: "text", text: "Done!" }],
      structuredContent: { success: true, result: "value" },
    };
  }
);
```

## Troubleshooting

### Discord Connection Issues

**Bot not connecting:**
- Verify your `DISCORD_TOKEN` in `.env` is correct
- Check the token hasn't been regenerated in Discord Developer Portal
- Ensure bot has proper intents enabled (Server Members, Message Content)

**Bot connected but can't see channels:**
- Check bot has "View Channels" permission
- Ensure bot role is positioned correctly in role hierarchy
- Verify bot has been added to your server

### MCP Server Issues

**Server won't start:**
```bash
# Check if port is already in use
lsof -i :3000

# Try a different port
HTTP_PORT=3001 npm start
```

**Tools not working:**
```bash
# Check server logs for errors
tail -f logs/discord-mcp.log

# Test with curl
curl http://localhost:3000/health
```

### Claude Code Integration Issues

**Claude Code can't connect:**
```bash
# Verify server is running
curl http://localhost:3000/health

# Check MCP server list
claude mcp list

# Remove and re-add the server
claude mcp remove discord-agent
claude mcp add --transport http discord-agent http://localhost:3000/mcp
```

**Tools not appearing:**
- Restart Claude Code after adding the server
- Check server logs for connection attempts
- Verify no firewall blocking localhost:3000

### Permission Errors

**Bot can't perform actions:**
- Verify bot has the required permission for the action
- Check bot's role position in server settings
- Ensure channel-specific permissions aren't blocking the bot
- Try giving bot "Administrator" permission temporarily for testing

## Security

### Best Practices

- **Never commit `.env` files** - Always use `.env.example` as a template
- **Rotate tokens regularly** - Regenerate bot token periodically
- **Use least privilege** - Only grant necessary Discord permissions
- **Secure your server** - Use firewall rules if exposing HTTP port
- **Monitor audit logs** - Check Discord's audit log for bot actions

### Token Security

Your Discord bot token should be treated like a password:

✅ **Do:**
- Store in `.env` file (gitignored)
- Use environment variables in production
- Regenerate if exposed
- Use Kubernetes secrets for cluster deployments

❌ **Don't:**
- Commit tokens to version control
- Share tokens publicly
- Embed tokens in code
- Expose tokens in logs

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with clear commit messages
4. Test thoroughly with a development Discord server
5. Submit a pull request

### Guidelines

- **Security First**: Never commit secrets or tokens
- **TypeScript**: Use strict typing and follow existing patterns
- **Documentation**: Update README and add JSDoc comments
- **Testing**: Test with a development server before submitting
- **Code Style**: Run `npm run lint` before committing

## License

MIT License - See [LICENSE](LICENSE) file for details

## Resources

- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification and documentation
- [Discord Developer Portal](https://discord.com/developers/applications) - Create and manage Discord bots
- [Discord.js Guide](https://discordjs.guide/) - Discord.js library documentation
- [Claude Code](https://claude.ai/claude-code) - AI-powered development assistant
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) - Official MCP SDK

## Support

- **Issues**: [GitHub Issues](https://github.com/aj-geddes/discord-agent-mcp/issues)
- **Discord.js**: [Discord.js Discord Server](https://discord.gg/djs)
- **MCP Protocol**: [MCP Specification](https://spec.modelcontextprotocol.io/)

---

Built with ❤️ using TypeScript, Discord.js, and the Model Context Protocol