@chinchillaenterprises/mcp-discord/README.md

Modular Discord MCP server with 45+ tools for comprehensive server management, featuring clean architecture and discord_ prefixed tools

# Discord MCP Server

Multi-account MCP server for Discord with secure credential storage and comprehensive bot management capabilities.

## Features

### Account Management (7 tools)
- **Multi-account support** - Manage multiple Discord bots/servers
- **Secure credential storage** - OS keychain integration with encrypted file fallback
- **Runtime switching** - Change between Discord accounts seamlessly

### Core Messaging (12 tools implemented, more coming)
- ✅ **Send messages** - Text and rich embeds with replies
- ✅ **Edit messages** - Modify bot's own messages
- ✅ **Delete messages** - Remove messages from channels
- ✅ **Add reactions** - React with emojis
- ✅ **Channel history** - Fetch recent messages
- 🚧 Pin/unpin messages
- 🚧 Send DMs
- 🚧 Forward messages
- 🚧 Send files

### Server Management (coming soon)
- 🚧 List guilds/channels
- 🚧 Member management
- 🚧 Role assignment
- 🚧 Permission management

## Installation

```bash
# Install globally with user scope
claude mcp add discord -s user -- npx @chinchillaenterprises/mcp-discord

# Or with environment variables
claude mcp add discord -s user \
  -e DISCORD_TOKEN="your_bot_token_here" \
  -e DISCORD_GUILD_ID="optional_guild_id" \
  -- npx @chinchillaenterprises/mcp-discord
```

## Setup

### 1. Create Discord Application

1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
2. Click "New Application" and give it a name
3. Go to "Bot" section
4. Click "Reset Token" and copy your bot token

### 2. Set Bot Permissions

In the Bot section, configure these permissions:
- Send Messages
- Read Message History  
- Manage Messages
- Add Reactions
- View Channels

### 3. Invite Bot to Server

1. Go to OAuth2 → URL Generator
2. Select scopes: `bot`
3. Select the permissions above
4. Copy the generated URL and open it
5. Select your server and authorize

### 4. Configure MCP Server

```bash
# Start Claude
claude

# Add your Discord account
"Use add_account to add a Discord bot with ID 'my-bot', name 'My Discord Bot', and token 'your_bot_token_here'"

# List accounts
"List my Discord accounts"

# Test messaging
"Send a message to #general saying 'Hello from Discord MCP!'"
```

## Usage Examples

### Basic Messaging

```
# Send text message (using channel name)
"Send a message to #general with text 'Hello Discord!'"
"Send 'Good morning!' to the announcements channel"

# Send rich embed (using channel name)
"Send an embed to #general with title 'Welcome' and description 'This is a test embed' with color 0x00ff00"

# Reply to a message
"Send 'Great question!' as a reply to message 1234567890 in #help-desk"

# Using channel IDs still works
"Send a message to channel 123456789012345678 with text 'Hello Discord!'"
```

### Message Management

```
# Edit a message
"Edit message 1234567890 in #general to say 'Updated message!'"

# Delete a message  
"Delete message 1234567890 from the announcements channel"

# Add reaction
"Add a 👍 reaction to message 1234567890 in general"
```

### Channel History

```
# Get recent messages
"Get the last 20 messages from #general"
"Show me recent messages in help-desk"

# Get messages before a specific message
"Get 50 messages from #announcements before message 1234567890"
```

### Channel Name Resolution

The Discord MCP server intelligently resolves channel names:
- **Exact match**: `#general` → finds "general" channel
- **Without hashtag**: `general` → finds "general" channel  
- **Partial match**: `announce` → finds "announcements" channel
- **Case insensitive**: `General` → finds "general" channel
- **Channel IDs**: `1390027279156908238` → uses ID directly

If multiple channels match, it uses the best match and logs alternatives.

## Account Management

### Add Account
```
{
  "id": "work-bot",
  "name": "Work Discord Bot", 
  "token": "your_bot_token",
  "guildId": "optional_guild_id",
  "setAsDefault": true
}
```

### Switch Accounts
```
"Switch to Discord account work-bot"
```

### List Accounts
```
"List all my Discord accounts"
```

## Available Tools

### Account Management
- `list_accounts` - List all configured Discord accounts
- `add_account` - Add new Discord bot configuration
- `switch_account` - Switch active Discord account
- `remove_account` - Remove account configuration
- `get_active_account` - Show current active account
- `set_default_account` - Set default account
- `update_account` - Update credentials

### Messaging Tools
- `discord_send_message` - Send messages with text/embeds
- `discord_edit_message` - Edit existing messages
- `discord_delete_message` - Delete messages
- `discord_add_reaction` - Add emoji reactions
- `discord_get_channel_history` - Fetch channel messages

## Security

- Bot tokens are stored securely using OS keychain (when available)
- Fallback to encrypted file storage with AES-256-CBC
- Credentials are never logged or exposed
- Each account is isolated

## Requirements

- Node.js 18+
- Discord bot token
- Discord server with bot invited

## Troubleshooting

### Bot not responding
- Check bot has required permissions in the channel
- Verify bot is online in Discord
- Ensure token is valid (starts with 'MTM...')

### Channel not found
- Verify channel ID is correct
- Ensure bot has access to the channel
- Check if it's a text channel (not voice)

### Permission errors  
- Bot needs "Send Messages" permission
- For editing/deleting: "Manage Messages"
- For reactions: "Add Reactions"

## Development

```bash
# Clone and setup
git clone https://github.com/ChinchillaEnterprises/ChillMCP.git
cd ChillMCP/mcp-discord
npm install

# Build
npm run build

# Test locally
claude mcp add discord-local -s user -- node $(pwd)/dist/index.js
```

## License

MIT - Chinchilla Enterprises

## Support

Report issues at: https://github.com/ChinchillaEnterprises/ChillMCP/issues