Discord MCP Server

A Model Context Protocol (MCP) server that provides Discord integration capabilities, including full file attachment support, rate limiting, and comprehensive Discord API features. Built with the official @modelcontextprotocol/sdk for maximum compatibility with Claude Code and other MCP clients.

Quick Start with Claude Code

# Add Discord MCP server to Claude Code (published on npm!)
claude mcp add discord -e DISCORD_BOT_TOKEN=your_token_here -- npx -y discord-mcp@latest

# Verify it's working
claude mcp list

# Start Claude and test with /mcp
claude

📦 Now available on npm! Install with npm install -g discord-mcp or use directly with npx. Latest version 2.3.1 uses the official MCP SDK with proper schema registration for full Claude Code compatibility.

Need a Discord token? See the Getting Your Discord Token section below.

Features

• Full Discord Integration: Send messages, manage channels, handle relationships, and update presence
• File Attachment Support: Upload and download files with proper MIME type handling
• Rate Limiting: Built-in rate limiter to respect Discord API limits
• Session Management: Secure token-based authentication
• Production Ready: Comprehensive error handling, structured logging, and Docker support
• Test Driven: 100% test coverage with Jest

Installation

Using npm

npm install
npm run build
npm start

Using Docker

docker build -t discord-mcp .
docker run -p 8080:8080 --env-file .env discord-mcp

Configuration

Copy .env.example to .env and configure:

# Required
NODE_ENV=production
DISCORD_BOT_TOKEN=your_bot_token_here

# Optional
PORT=8080
LOG_LEVEL=info
MAX_UPLOAD_MB=25

Available Tools

Messages

• discord_send_message - Send messages with optional file attachments
• discord_edit_message - Edit existing messages
• discord_delete_message - Delete messages
• discord_add_reaction - Add reactions to messages
• discord_remove_reaction - Remove reactions from messages

Files

• discord_download_attachment - Download Discord CDN attachments
• discord_cleanup_download - Clean up temporary download files

Channels

• discord_get_channel - Get channel information
• discord_get_dm_channels - List DM channels
• discord_create_dm - Create or fetch DM channel

Relationships

• discord_get_friends - Get friends list
• discord_add_friend - Send friend request
• discord_remove_friend - Remove friend

Presence

• discord_update_presence - Update Discord presence/status
• discord_clear_presence - Clear current presence

Available Resources

• discord://channel/{channelId} - Channel information
• discord://dm-channels - List of DM channels
• discord://users/@me - Current user information
• discord://users/{userId} - User information
• discord://friends - Friends list

Adding to Claude Code

Claude Code provides native MCP server integration. Here's how to add this Discord MCP server:

Method 1: From Published npm Package (Recommended)

# Add the Discord MCP server to your project
claude mcp add discord -- npx -y discord-mcp@latest

# Or add globally for all projects
claude mcp add -s user discord -- npx -y discord-mcp@latest

Method 2: From Local Installation

# First, install the server
npm install -g discord-mcp

# Then add to Claude Code
claude mcp add discord -- discord-mcp

# Or for project-only access
claude mcp add -s project discord -- discord-mcp

Method 3: From Local Development

If you're developing locally or want to use this exact repository:

# Clone and build this repository
git clone https://github.com/yourusername/discord-mcp.git
cd discord-mcp
npm install
npm run build

# Add to Claude Code with full path
claude mcp add discord -- node /full/path/to/discord-mcp/dist/index.js

Method 4: With Environment Variables

For secure token management:

# Add with your Discord token
claude mcp add discord -e DISCORD_BOT_TOKEN=your_bot_token_here -- npx -y discord-mcp@latest

# Or reference a .env file location
claude mcp add discord -e ENV_FILE=/path/to/.env -- npx -y discord-mcp@latest

Verification

After adding the server, verify it's working:

# List all MCP servers
claude mcp list

# Check the Discord server specifically
claude mcp get discord

# Start Claude and test the server
claude

In Claude, type /mcp to see all available servers and test the Discord integration.

Server Configuration Options

When adding the server, you can customize behavior:

# With custom upload limit
claude mcp add discord \
  -e DISCORD_BOT_TOKEN=your_token \
  -e MAX_UPLOAD_MB=50 \
  -e LOG_LEVEL=debug \
  -- npx -y discord-mcp@latest

# For production use
claude mcp add discord \
  -e DISCORD_BOT_TOKEN=your_token \
  -e NODE_ENV=production \
  -e LOG_LEVEL=info \
  -- npx -y discord-mcp@latest

Project-Scoped Setup (Team Sharing)

For teams, add the server to your project's .mcp.json:

# Add to project scope (creates .mcp.json)
claude mcp add -s project discord \
  -e DISCORD_BOT_TOKEN=your_token \
  -- npx -y discord-mcp@latest

This creates a .mcp.json file in your project root that teammates can use:

{
  "discord": {
    "command": "npx",
    "args": ["-y", "discord-mcp@latest"],
    "env": {
      "DISCORD_BOT_TOKEN": "your_bot_token_here"
    }
  }
}

Important: Don't commit real tokens to git. Use environment variables or local .env files.

Getting Your Discord Token

This server supports both bot tokens and user tokens:

Bot Token (Recommended for Development)

1. Go to Discord Developer Portal
2. Create a new application
3. Go to "Bot" section
4. Copy the bot token
5. Invite the bot to your server with appropriate permissions

User Token (Advanced - Violates Discord ToS)

User tokens provide additional features like DMs and friend management but violate Discord's Terms of Service.

⚠️ Warning: Using user tokens may result in account termination. Use at your own risk and only for personal testing.

To extract your user token:

1. Open Discord in your browser
2. Open Developer Tools (F12)
3. Go to Application/Storage → Local Storage → discord.com
4. Find the "token" key and copy its value

Troubleshooting

If the server doesn't start:

# Check server status
claude mcp list

# Test the server directly
DISCORD_BOT_TOKEN=your_token npx discord-mcp

# Debug with verbose logging
DEBUG=* claude mcp add discord -- npx -y discord-mcp@latest

Common issues:

• Invalid token: Verify your Discord token is correct
• Network errors: Check your internet connection
• Permission errors: Ensure the bot has necessary Discord permissions
• Rate limiting: The server handles this automatically, but excessive use may trigger longer delays

Using with Other MCP Clients

For non-Claude Code clients, start the server manually:

# Start with environment variables
DISCORD_BOT_TOKEN=your_token npm start

# Or with .env file
npm start

Connect your MCP client to http://localhost:8080 or use stdio transport.

Development

Setup

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Build the project
npm run build

# Run in development mode
npm run dev

Testing

The project uses Jest for testing with 100% coverage:

npm test          # Run all tests
npm run test:coverage  # Run tests with coverage report

Project Structure

discord-mcp/
├── src/
│   ├── config.ts          # Configuration management
│   ├── index.ts           # Server entry point (McpServer)
│   ├── session.ts         # Session middleware
│   ├── discord/
│   │   ├── service.ts     # Discord API wrapper
│   │   ├── rate-limit.ts  # Rate limiting
│   │   └── file.ts        # File handling
│   ├── tools/             # MCP tools (15 tools)
│   │   ├── messages.ts
│   │   ├── files.ts
│   │   ├── channels.ts
│   │   ├── relationships.ts
│   │   └── presence.ts
│   ├── resources/         # MCP resources
│   │   ├── channels.ts
│   │   └── users.ts
│   └── utils/
│       ├── errors.ts      # Error types
│       ├── logger.ts      # Logging setup
│       └── mime.ts        # MIME type handling
└── tests/                 # Test files

Security Considerations

• Never commit your Discord bot token
• Use environment variables for sensitive configuration
• The server validates all file uploads against allowed MIME types
• Rate limiting prevents API abuse
• All errors are properly sanitized before returning to clients

Rate Limiting

The server implements Discord's rate limiting:

• Global limit: 50 requests per second
• Per-route limits based on Discord API
• Automatic retry with backoff on rate limit hits

File Handling

Supported file types:

• Images: png, jpg, jpeg, gif, webp, svg, ico, bmp
• Documents: txt, pdf, doc, docx, xls, xlsx, csv, md
• Archives: zip, tar, gz, rar, 7z
• Code: json, xml, yaml, yml, html, css, js, ts, py, java, cpp, c, h, hpp, rs, go, rb, php

Maximum file size: 25MB (configurable)

Error Handling

The server provides detailed error messages with proper error types:

• UserError - User-facing errors (invalid input, etc.)
• DiscordAPIError - Discord API errors with status codes
• RateLimitError - Rate limit errors with retry information
• FileError - File handling errors

Logging

Structured JSON logging with Pino:

• Configurable log levels
• Request/response logging
• Error tracking with stack traces
• Performance metrics

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Write tests for your changes
4. Ensure all tests pass (npm test)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

License

MIT

Support

For issues and feature requests, please use the GitHub issue tracker.

Architecture

This server is built using the official Model Context Protocol SDK (@modelcontextprotocol/sdk), which provides:

• Native MCP protocol implementation with McpServer class
• Direct tool registration with server.tool() method and proper schema exposure
• Automatic Zod schema handling and validation via tool.parameters.shape
• Built-in stdio transport support
• Full compatibility with Claude Code and other MCP clients
• Proper error handling with McpError types

Recent Updates

Version 2.3.1 - Parameter Validation Fix

• Fixed: Resolved "Invalid Form Body" errors for parameterized tools
• Changed: Proper Zod schema registration using tool.parameters.shape
• Removed: Unnecessary parameter transformation logic
• Improved: Simplified error handling and validation flow

All Discord MCP tools now work correctly in Claude Code with proper parameter validation.