# 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:

```bash
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](https://github.com/settings/tokens/new?scopes=read:packages))
- **Email**: Your email

### Step 2: Install globally

```bash
npm install -g @acheronlabs/mcp-discord
```

### Step 3: Configure your Discord token

```bash
mcp-discord-setup
```

Follow the prompts to enter your Discord token (see [Getting Your Token](#getting-your-discord-token)).

### Step 4: Add to Claude Code

**Option A: Global (available in all projects)**

Run this command to add globally:

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

**Option B: Per-project**

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

```json
{
  "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](#getting-your-discord-token))

## Installation

### Option 1: Global Install from GitHub Packages (Recommended)

See [Quick Start](#quick-start-team-members) above.

### Option 2: Clone and Build (Development)

```bash
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:

```bash
# 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`:

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

Or if installed globally:

```json
{
  "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:

```bash
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:
```bash
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:

```bash
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