keithah/discord-guild-rag

Discord Guild RAG System

A Retrieval-Augmented Generation system for Discord messages that allows you to query your Discord guild history with natural language directly in Claude Desktop via MCP (Model Context Protocol).

Features

• Export existing Discord messages from specified channels
• Real-time message collection via Discord bot
• Vector-based search using sentence embeddings (ChromaDB)
• Claude Desktop Integration - Direct MCP server connection for seamless querying
• Rich CLI interface with filtering options
• No copy-paste needed - Claude Desktop directly queries your Discord database

Quick Start

1. Deploy & Test

git clone https://github.com/keithah/discord-guild-rag.git
cd discord-guild-rag
./deploy.sh   # Sets up environment and creates config template
./test.sh     # Runs comprehensive system tests

2. Configure Discord

Edit config/.env with your Discord credentials:

DISCORD_BOT_TOKEN=your_bot_token
DISCORD_GUILD_ID=your_server_id  
ALLOWED_CHANNELS=channel1,channel2,channel3

See Discord Bot Setup below for detailed instructions.

Discord Bot Setup

1. Go to Discord Developer Portal
2. Create a New Application
3. Go to "Bot" section and create a bot
4. Copy the bot token
5. Enable "Message Content Intent" under Privileged Gateway Intents
6. Invite bot to your server with "Read Message History" permissions

3. Configure Environment

Edit config/.env with your Discord credentials:

DISCORD_BOT_TOKEN=your_actual_bot_token_here
DISCORD_GUILD_ID=your_server_id_here
ALLOWED_CHANNELS=channel_id_1,channel_id_2,channel_id_3

To get IDs: Enable Developer Mode in Discord → Right-click → Copy ID

Deployment Options

• Quick Test: Use ./deploy.sh and ./test.sh for local testing
• Docker: Use docker-compose up -d for containerized deployment
• Production: See for detailed deployment guide

Usage

Initial Setup - Export Existing Messages

# Export all messages (first time setup)
python -m src.main export

# Export with limit for testing
python -m src.main export --limit 1000

Start Real-time Collection

# Start the Discord bot to collect new messages
python -m src.main bot

Search Your Messages

# Basic search
python -m src.main search "What did we decide about the server migration?"

# Filtered searches
python -m src.main search "project updates" --channel "dev-team" --author "john"

# Export formatted context for Claude
python -m src.main search "bug reports" --export

# Show context in terminal and export to file
python -m src.main search "team meeting notes" --show-context --export

Check System Status

python -m src.main status

Claude Desktop Integration

The system provides an MCP server that integrates directly with Claude Desktop - no copy-paste needed!

Quick Setup for Claude Desktop

1. Setup the system: Follow the installation steps above
2. Configure Claude Desktop: Add the MCP server to your Claude Desktop config
3. Start querying: Ask Claude Desktop to search your Discord messages directly

For detailed Claude Desktop setup instructions, see

Example Claude Desktop Usage

Once configured, you can directly ask Claude Desktop:

• "Search my Discord messages for API performance discussions"
• "Find recent conversations about deployment issues in the #backend channel"
• "What were the main concerns raised about the database migration?"

Claude Desktop will use the MCP server to search your Discord database and provide contextual responses.

CLI Commands

Search Options

Project Structure

discord-guild-rag/
├── src/
│   ├── database.py          # ChromaDB operations
│   ├── rag_processor.py     # Embeddings and search
│   ├── discord_exporter.py  # Export existing messages
│   ├── discord_bot.py       # Real-time collection
│   ├── query_interface.py   # Search interface
│   └── main.py             # CLI commands
├── data/
│   ├── exports/            # Raw Discord exports & Claude contexts
│   └── embeddings/         # ChromaDB storage
├── config/
│   ├── .env               # Environment variables
│   └── config.yaml        # Configuration settings
└── requirements.txt

Use Cases

Debugging Past Issues

python -m src.main search "database connection errors" --channel "backend" --export
# Copy to Claude: "What caused these database errors and how were they fixed?"

Team Decision Review

python -m src.main search "migration timeline" --author "tech-lead" --export
# Copy to Claude: "Summarize the migration timeline decisions and concerns raised"

Project Status Check

python -m src.main search "feature release" --results 20 --export
# Copy to Claude: "What's the current status of our feature releases?"

Troubleshooting

Common Issues

• Bot permissions: Ensure bot has "Read Message History" permission
• Channel IDs: Use Developer Mode in Discord to copy channel IDs
• Rate limits: Discord has rate limits - the bot handles this automatically
• Memory usage: For large servers, consider processing in batches

Performance Tips

• Start with a limited export to test the system
• Use channel filtering to focus on relevant conversations
• Monitor database size and embedding storage

Benefits

• ✅ Direct Claude Desktop Integration - No copy-paste needed via MCP
• ✅ Smart search - RAG finds the most relevant messages automatically
• ✅ Full context - Claude gets direct access to your Discord history
• ✅ Incremental updates - New messages are automatically processed
• ✅ Privacy - Everything runs locally on your machine
• ✅ Real-time - Ask questions naturally in Claude Desktop

Configuration

Embedding Model

The system uses all-MiniLM-L6-v2 by default. You can change this in config/config.yaml:

rag:
  embedding_model: "all-MiniLM-L6-v2"  # or "all-mpnet-base-v2" for better quality

Database Settings

database:
  chroma_path: "./data/embeddings"
  collection_name: "discord_messages"

Advanced Usage

Custom Export Locations

# The system automatically creates timestamped export files
# Files are saved to: data/exports/claude_context_[query]_[timestamp].md

Filtering by Date

Currently implemented for future use - can be extended to filter by date ranges.

Multiple Servers

To handle multiple Discord servers, create separate configuration files and run multiple instances.