mcp-discord

An MCP (Model Context Protocol) server that enables searching Discord messages using Discord's native search API. Designed for use with Claude Code to find project decisions and communications in Discord.

Quick Start (Team Members)

Step 1: Configure npm for GitHub Packages

Run this once to set up access to our private package:

npm config set @acheronlabs:registry https://npm.pkg.github.com
npm login --registry=https://npm.pkg.github.com

When prompted:

• Username: Your GitHub username
• Password: A GitHub Personal Access Token with read:packages scope (create one here)
• Email: Your email

Step 2: Install globally

npm install -g @acheronlabs/mcp-discord

Step 3: Configure your Discord token

mcp-discord-setup

Follow the prompts to enter your Discord token (see Getting Your Token).

Step 4: Add to Claude Code

Option A: Global (available in all projects)

Run this command to add globally:

claude mcp add discord-search --scope user -- mcp-discord

Option B: Per-project

Add to your project's .mcp.json file:

{
  "mcpServers": {
    "discord-search": {
      "command": "mcp-discord"
    }
  }
}

Step 5: Restart Claude Code

Restart Claude Code and verify with the /mcp command.

Features

• Search Messages: Full-text search with filters for author, channel, date range, and attachment types
• List Guilds: View all Discord servers you have access to
• List Channels: Browse channels in a server
• Message Context: Get surrounding messages for context around search results
• Daily Summary: Get aggregated messages over a time period with author statistics (rate-limit safe)

Prerequisites

• Node.js 24+
• Discord user token (see Getting Your Token)

Installation

Option 1: Global Install from GitHub Packages (Recommended)

See Quick Start above.

Option 2: Clone and Build (Development)

git clone https://github.com/AcheronLabs/mcp-discord.git
cd mcp-discord
npm install
npm run build
npm run setup

Configuration

1. Run Setup (Recommended)

The easiest way to configure the server is using the interactive setup:

# If installed globally
mcp-discord-setup

# Or after cloning and building
npm run setup

This will:

• Guide you through getting your Discord token
• Store it securely in ~/.config/mcp-discord/config.json
• Set proper file permissions (600 - owner read/write only)

2. Configure Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "discord-search": {
      "command": "node",
      "args": ["/path/to/mcp-discord/dist/index.js"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "discord-search": {
      "command": "mcp-discord"
    }
  }
}

3. Restart Claude Code

After configuring, restart Claude Code for changes to take effect. Verify with /mcp command.

Alternative: Environment Variable

If you prefer environment variables (e.g., for CI/CD), you can set:

export DISCORD_USER_TOKEN="your_token_here"

The server checks config file first, then falls back to environment variable.

Getting Your Discord Token

1. Open Discord in your browser at https://discord.com/app
2. Open Developer Tools (F12 or Cmd+Option+I)
3. Go to the Network tab
4. Perform any action in Discord (send a message, switch channels)
5. Click on any request to discord.com/api
6. Look for the Authorization header in the request headers
7. Copy the token value (without "Bearer " prefix if present)

Security: Your token is stored in ~/.config/mcp-discord/config.json with 600 permissions (only you can read/write).

Available Tools

search_messages

Search Discord messages with powerful filters.

Parameter	Type	Required	Description
guild_id	string	Yes	Server ID to search in
content	string	No	Text to search for
author_id	string	No	Filter by user ID
channel_id	string	No	Filter to specific channel
has	enum	No	Filter by: file, link, embed, image, video, sound, sticker
before	string	No	Messages before date (ISO 8601) or message ID
after	string	No	Messages after date (ISO 8601) or message ID
limit	number	No	Max results 1-25 (default: 25)
offset	number	No	Pagination offset

Response includes: guild_name, channel_name, author, content, timestamp, attachments for each message.

Example usage in Claude:

Search the Dimensional server for "mini pc" references

list_guilds

List all Discord servers you have access to. No parameters required.

list_channels

List channels in a Discord server.

Parameter	Type	Required	Description
guild_id	string	Yes	Server ID
type	enum	No	Filter: text, voice, category, thread, forum, all (default: text)

get_message_context

Get messages surrounding a specific message for context.

Parameter	Type	Required	Description
guild_id	string	Yes	Server ID containing the message
channel_id	string	Yes	Channel containing the message
message_id	string	Yes	Target message ID
content	string	No	Text from the target message (recommended for reliable results)
before_count	number	No	Messages before (0-25, default: 5)
after_count	number	No	Messages after (0-25, default: 5)

Note: The content parameter is recommended because Discord's search API requires content to reliably find specific messages. Without it, the target message may not be found.

get_daily_summary

Get a summary of all messages from a Discord server over a time period. Useful for daily digests.

Parameter	Type	Required	Description
guild_id	string	Yes	Server ID to summarize
channel_ids	string[]	No	Specific channel IDs (default: all channels)
hours	number	No	Hours to look back (1-168, default: 24)
max_messages	number	No	Max messages to fetch (25-1000, default: 500)

Rate Limiting: Uses conservative 500ms delays between API requests (2 req/sec) to avoid Discord blocks. A full 500-message fetch takes ~10 seconds.

Response includes:

• stats: Total messages, channels, authors, API calls made, truncation info
• active_authors: Top 20 most active users with message counts
• channels: Messages grouped by channel, sorted by activity

Example usage in Claude:

Give me a daily summary of the Dimensional server
Summarize the last 48 hours of messages in the dev channel

Usage Examples

Once configured, you can ask Claude:

• "List my Discord servers"
• "Search the Dimensional server for discussions about hardware"
• "Find messages from @alex about navigation"
• "Show me messages with attachments in the dev channel"
• "Get context around message ID 1234567890" (use with content text for best results)
• "Give me a daily summary of the Dimensional server"

Troubleshooting

MCP server not appearing

1. Check /mcp command output for errors
2. Verify token is configured: cat ~/.config/mcp-discord/config.json
3. Ensure the path in .mcp.json is absolute
4. Restart Claude Code

Token not found

Run the setup again:

npm run setup

"Rate limited" errors

The server handles rate limits automatically with retries. If you see persistent rate limit errors, wait a few minutes before trying again.

"Discord API error (401)"

Your token is invalid or expired. Get a fresh token from Discord.

"Discord API error (403)"

You don't have permission to access that server or channel.

Notes

• This uses Discord's user token (not a bot token) to access the native search API
• Using user tokens is against Discord's Terms of Service - use at your own risk for personal productivity
• The server caches channel and guild information for better performance
• Search results are limited to 25 per request (Discord API limit)

Publishing a New Release (Maintainers)

To publish a new version to GitHub Packages, just run:

npm run release

This will automatically:

1. Run tests and build
2. Bump the version (you'll be prompted for patch/minor/major)
3. Create a git tag
4. Push to GitHub
5. Create a GitHub Release

The GitHub Release triggers the publish workflow, which publishes to GitHub Packages.

License

MIT